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Introduction 
Pink is Apple’s new system software architecture. It draws on the strengths of Macintosh, but also: 


introduces a new programming model and architecture designed to open up new opportunities for Apple 
and third party developers. This document gives an overview of the architecture of the Pink system. 


Architectural Goals 


Pink has several important architectural goals which are crucial to meeting the project goals of opening 
new opportunities for Apple and developers. 


Flexibility and Expandability 


Apple sometimes has diff 
architecture. This is partl: 
team, which are deeply 41 
to add some new syste 
built. Worse, these assu 


Pink aims to be more 
easily change and ex 
to grow to deal wit 


No system is infinit 
and sooner or later 
the system and to ease the Barden of 


The key to such flexibility is careful managerr 
assumptions must underlie every engineerin 
you must, and to isolate such assumptions w 
Pink achieves this.ebjecti 


There are two 


the level of information ow. _ Base classes provide the minimum p r dealing with an 


object; derived classes provide extra information for those who need to know. 


Objects, of course, are not enough. Pink cannot meet its goal of flexibility without care and diligence on 
the part of all designers. 


Portability 


Apple does not currently have the option of moving its system software to another hardware platform. 
This is because it is written almost entirely in 68000 assembly language, driven by the need to fit in small 
amounts of memory (ROM and RAM). Although memory will never be free, our hardware has grown to 
the point where Apple can afford to trade off some memory consumption for the ability to run on plat- 
forms other than the 68000. Having this ability lets Apple take maximum advantage of competition 
among microprocessor vendors. This enables us to introduce important new products like Jaguar. Con- 
sidering the agony of developing a complete suite of system software, the company’s best interests de- 
mand we not tie Pink to a specific processor architecture. 
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“The only reasonable numbers are one and infinity.” Thus, portability means more than portability to 
Jaguar. There will be other machines beyond Jaguar. Some day, the company might even want to run 
Pink on something really obscure, like an Intel processor (“bite your tongue!”). 


To meet this goal in Pink, all but the most performance critical code is being written in a processor- and 
system-independent fashion. There will be code in Pink which varies from implementation to implemen- 
tation, but it must be carefully controlled. Note that “portable” does not mean “least common denomina- 
tor”. Every platform will have distinguishing features which Pink can and must take advantage of. Parts 
of the system may change significantly from platform to platform. Again, the key is management of as- 
sumptions to give the most flexibility possible. 


Performance 
Like any large system, Pink carries the risk of inadequate performance. The processor hasn’t been de- 


signed .which can’t be brought to its knees by inattention to this goal. Pink Tust perform well on M C c I 
class machines, to the pon \ : 


Robustness 


makes no allowance for th 
errors that engineers make. In addition 
don’t place the user’s data at risk. 


An example illustrates why architecture places 
Any system which cpalaile so-called unsafe | 
tba 


Pink solves this problem by eliminating low memory from the address space. The first N (currently 16 
megabytes) locations of the address space simply don’t exist, and any reference results in an immediate 
error. This is just one example of how an architecture can plan ahead for programmer errors. 


Empower Developers 


In addition to goals motivated by Apple’s needs, Pink has the goai of making it easier for developers to 
build great applications. There are two thrusts to this goal: first, to allow the developer to concentrate on 
their application domain by removing much of the boilerplate code associated with developing a Macin- 
tosh application. Second, to raise the ante for applications by introducing major new system-wide fea- 
tures which enhance applications. 


Saving a file is an excellent example of the first area. There are more than twenty steps to follow to correct- 
ly save a file in a way that is AppleShare friendly, deals with disk full, handles errors, works around Poor 
Man’s Search Path, etc. These steps are documented in twenty different places. MacApp solves the prob- 
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lem by dealing with the issue itself, asking the developer only to provide the data to be saved. Pink takes 
the same approach. 


Examples of the second area are linking, provided by CHER, and the Albert 2D/3D graphics system. 
CHER empowers developers first by providing lots of default functionality to every application, and sec- 
ond by allowing applications to build on top of what CHER provides. Albert empowers developers by 
giving them an extremely rich (but non-fattening) graphics system with more capabilities than anything 
else in the industry. Developers don’t use transformation matrices, anti-aliasing, and 3D in their applica- 
tions today because there would be no time left for the application after implementing all those capabili- 
ties. If it’s built in, people use it. 


Support the Interface 


The Macintosh has a well defined human interface, and a set of human interface design principles, but al- 
most no system support for implementing those principles. Consequently, developers must make a major 
effort to support those prin mplemented at all. For example, direct manipe 
tion is a cornerstone of the: nit 
tosh applications could e> 
windows, pull-down mer 


ery few applications implem: 
ith a character display,: 


ypers is to conform to 
ds support for direct ma- 
fact, it will be required to 


Pink directly supports t 
the human interface exé 
nipulation, so that it i 
fully integrate an ap 


uman interface. The path of least resistan 
tly, with deviations requiring extra work 
e range of applications to ma 
the desktop level. 


A Global System 


The Macintosh is one of the few'e6r 
world. Unfortunately, it aimed too lo 
support for non-European languages was 
tion, the problems caused by not including th 
from writing truly global applications. 


h deal with puage 
Itiple natu . 


Architectural Princi 


This section discusses some techniques which are not goals themselves, but are intended to help us reach 
the goals discussed above. 


_ All Interfaces through Objects 


In order to get the most flexibility we can (by hiding as many assumptions as possible), the only client in- 
terface to services is through classes and objects of those classes. Among other things, this means that the 
following (usually important) concepts should never be part of an interface: messages, file formats, data 
formats, IPC. Note that these are all services themselves which can be used in the implementation of other 
services, but that they should never be part of that service’s interface. 


For example, you may well implement a service using the Scream client/server classes, but that fact 
should be completely hidden from the clients of that service. After all, you may want to change to an im- 
plementation based on shared memory and libraries instead of messages and servers, and the client 
doesn’t need to care. Part of the problem with the Macintosh architecture is that interfaces are defined at 
too low a level (“the parameter block is laid out like this”, “send a message which has these bytes in this 
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order”, etc.). 


Just using objects isn’t enough; the objects must be designed correctly. Objects in Pink are defined in 
terms of the abstraction being presented to the client, not the implementation. It’s quite easy to spill your . 
implementation’s guts through a class interface. The key is to design the class thinking about it from the 
client’s point of view. What are the entities being dealt with? What do I need to know about them? What 
operations can I perform on them? These are the key object design questions. 


Manage Commonality through Inheritance 


Commonality in software systems has traditionally been managed by commonality of implementation. 
For example, UNIX’ systems manage devices by making everything look like a block device or a charac- 
ter device. Device specific features are glued on through extensions. The Macintosh architecture uses the 
same approach: devices all support the same small set of calls, except that there are usually 1,897,422 vari- 
ants of the control call to handle the specific attributes of a device. 


Type inheritance provide 
mon to many objects. S 
they implement the con 
stract base classes can 5 
can inherit from mult 


defines an abstraction and i which is com- 


etined, yielding sticcessively more refined pa 
base classes, thus supporting more than o 


The benefit to clien 
abstract base class a 
details to change, 0} 


Note that inheritance:of ¢ 
should be dealt with by h has-a 
relationship), or protected interfaces." from 
the same base class. 


other abstract 
formance disk with nterface card; its driver would inher 
MNubusDevice. In each ¢ ients deal only with the protocol they care a d unnecessary detail 
is hidden. Similarly, a video NuBus card would be a TVideoDevice and an MNubusDevice. 


Leverage Where Possible 


Using an existing object rather than inventing a new one is a good way to achieve several Pink goals. Less 
code means a smaller memory footprint, which yields better performance. Fewer classes means less for 
the developer to learn. Less to implement means fewer bugs, leading to a more robust system. It also 
means we get done faster, leading to bigger profit cores checks (this is an implicit Pink goal not men- 
tioned above). 


For example, Pink has a set of collection classes which implement common data structures from Comput- 
er Science (note capital letters), such as stacks, sets, trees, etc. Pink uses these classes heavily to avoid 
reinventing the wheel. Similarly, the many building block classes Pink provides allow the developer to 
concentrate on his or her application rather than reinventing common tools. 


1. [don’t care whose trademark it is. So there. 
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Sometimes this requires battling habits learned in previous lives. For example, the AppleTalk datagram 
protocol (DDP) has a concept of a socket. A machine may have up to 256 sockets, which are mostly allo- 
cated dynamically. The first inclination might be to use a bit vector to keep track of which socket numbers 
have been allocated. This leads to a fair amount of custom code. If you look more closely at the applica- 
tion, however, you notice that first, there is only one such data structure per CPU, and second, perfor- 
mance is not a critical issue. Instead of building a custom data structure, the existing classes TSet and 
TCollectibleLong could be used to implement a set of integers, which is precisely what a bit vector is. 


Naturally, leverage does not mean “one size fits all” (TProcrustes?). In another context, speed or space 
performance may demand that a custom data structure be used. That’s OK. As Einstein said, “Everything 
should be as simple as Possioles but no simpler.” 


Frameworks Protect Subsystems from Each Other 


Use of objects and inheritance help isolate clients from Se and unneeded details, but what 

about developers implementing de ska . 
tions about the objects, but 
the idea of frameworks. 


The Lisa Toolkit and M 
classes, among them T 
client from the system a 
tion hiding goes both ¥ 
used by developers. 

oper and the system: 
veloper deals with 


de the details of the 
m the client; the informa- 
\pp system, and parts are 


Let's recycle an ear 


method when creating his or her own subclass: 
document. This is only one of the twenty or so’ 


tocol is impleme! 
steps be added 


The MacApp application us protected from the details of ts, and the de- 

OI of documents which are irrelevant. The TD nt framework class 
has interfaces which go both ways: one for clients, and another for subclasses (of course, these can over- 
lap somewhat). 


Pink uses frameworks extensively. In addition to the MacApp application and document frameworks, 
Pink adds: a client/server framework, a graphics device framework, a concurrency control and recovery 
framework, several frameworks for implementing different kinds of device drivers (NuBus, SCSI, video, 
disk, etc.), a text editing framework, a framework for file systems, and more. This structuring technique 
made MacApp possible, and it’s an important part of Pink. 


Let Resources Find You 


Traditionally, programs have names of resources or collections of resources hard wired into them, and go 
out looking for these resources. Yet programs do not usually need to know this information, and fre- 
quently it’s only used to put up a list for the user to choose from. Needless to say, having many different 
programs write their own code to find things and then to put them up in lists for the user to choose is not 
in keeping with the Pink principle of hiding assumptions and information. 
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Pink instead takes the approach that code should wait for resources to find it, rather than looking for re- 
sources. A form of this happens today on the Macintosh. The file system does not know about all possible 
devices which can act as disks, and go out looking for them. If it did, it would be impossible to create 
things like tape disks or NuBus disks, simply because the file system would have contained the (unneces- 
sary) assumption that, say, only SCSI disks can contain file systems. Instead, the Macintosh file system 
waits for resources to find it through the drive queue data structure. Anything can declare itself to be ca- 
pable of holding a file system by inserting an entry in the drive queue. 


Pink takes this idea as an architectural principle, and takes it one step further. First, resources should reg- 
ister themselves with services; services should not go out looking for resources. This is a “bottom up” ap- 
proach rather than the traditional “top down” approach. Second, whenever possible resources should 
register themselves on the desktop, and services should be told what resources to use via choices from the 
desktop, so that users have to remember only one way to “choose” things. 


Here is one example of these punapes in action. At boot time, the SCSI software must enumerate the de- 
vices attached to the system and: sak 45 ‘for each device. However, this is thelast : 

SCSI devices need to be ni 
lowed). From this point « 
sources it represents. 


volumes to be moun 
the user to select thei 
formation. The file 
tape, SCSI, NuBus, 
source is selected @ 
Similar techniques work forot 


This architecture solves several problems 
increases flexibility. For example, the App 
the SCSI chain. A Pink scanning application w 
whether it was on SCSI, Nubus, or whatever (z 


Second, since res 
This prevents 
way, network 
in a third place an 


Naturally, some things don’t fit this model. Although fonts need to be manipulated on the desktop, I 
doubt users would like to select them this way when writing a document. Thus, some resources may 
need to be registered in more than one place and presented in more than one way. 


Architectural Overview and Issues 


This section gives a broad overview of the architecture of the system. It’s supposed to be a complete 
synopsis, but will probably only approach that goal asymptotically. As I discuss each functional area, | 
will also enumerate the open issues and coming attractions. 


The Opus/2 Kernel 


Any view of the Pink architecture must start with the fundamentals of the programming model and envi- 
ronment. The foundation of that environment is the Opus/2 Kernel. 
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Opus is an operating system kernel which provides a small set of powerful abstractions. It follows in the 
same spirit of previous such kernels, like Stanford University’s V and Carnegie Mellon University’s 
Mach. The design goal of Opus is to abstract away the variations of machine architecture while at the 
same time remaining small, leaving as much as possible to code running outside the kernel. 


The primary abstractions that Opus provides are: 


e Multiple, independent virtual address spaces. Each address space is associated with a team (see 
below). 


¢ Multiple mapped segments” within an address space. Each segment has a corresponding backing 
store, which may be a file on disk, part of the physical address space, or anything else. Segments are 
usually demand paged, unless otherwise requested. Segments can be mapped into more than one 
virtual address space simultaneously, allowing communication via shared memory. 


¢ Multiple threads of execit 
lection of tasks in ana 
the entire address spa¢ 
sor Pink is running on: 


ace. Each thread is known as at 


ute in the “user’ ‘ (unpri ode of the proces- 
4s) on a machine via a. 


responding kernel resources. The entire Pink: 
handlers and the kernel itself, all Pink code is’ 
of one or more teams. Shared memory and IP 


services and I/ ag ; ; to appli- 
cations are also em code (obviou ing ci lencies, e. yf the disk 
driver can’t be p 


Opus Issues 


¢ Currently, access to shared memory is synchronized via semaphores implemented in library code. 
This function is likely to migrate into the Opus kernel, and may be replaced by a model of monitors 
and conditions. 


¢ Certain real time applications such as sound, video, and human interface do not work well with a pri- 
ority based scheduler. The system scheduling model is likely to expand to support real time require- 
ments, by including concepts like deadlines or periodic scheduling (this may be in the kernel or lay- 
ered on top). 


e Currently, segments which do not correspond to physical address space must be backed by disk files. 
This will be changed to support segments backed by other stores, as well as segments (such as caches) 
which do not have backing store at all. Ona related note, the interface for segments is currently closely 

. tied to the file system. It will become more independent in the future. 


2. OK, so it’s a horrid name. So sue me. 
3. An archaic acronym, for Inter Process Communication. 
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* Currently, IPC, semaphores, and paging do not take priorities into account (i.e., the queuing is “fair”). 
This is probably not appropriate for an interactive, real time system. We will experiment with these is- 
sues to find the right approach. 


* Several clients need “copy on write” functionality for segments. This will be provided by a “lazy eval- 
uation” copy function. 


The Run Time Environment 

The Pink run time system builds a programming model on top of the abstractions of the Opus/2 kernel. 
This programming model is designed to support the classic Algol family of languages: C, Pascal, Fortran, 
and so on. In addition, the run time supports an object programming model based on the semantics of 


C++. Finally, there is a set of features specific to Pink. 


Shared Libraries and Classes 


One of the most importa 
functions and global data 
teams which reference th > at 

variables. Shared librarig \ hen a library is load- 
ed. This may cause oth i i : i : Fe provided via shared li- 
braries supplied by Ap 


ared libraries. A shared libra 


This does not mean t! ites s ibraries. ecture allows j an indefinite 
number of shared lib: E ‘ 

“system software”. 
run time mechanisi 


Shared libraries are normally mapped 
ROM. Unlike the Macintosh, there is no diff % k. To 
support ROM, shared libraries can be patche¢ 

function is exported from the library. 


| Static references wh : i 1 iries, 


be loaded by n e. This 
capability grea power of in- 
heritance. . 

Language Support 


The Pink run time also has the following features: 
* Standard C, C++ (minus AT&T's task package), and SANE (including complex) libraries. 
e Fast semaphores for synchronization of shared memory. 


* Very fast storage allocation which is safe for use by multiple tasks. This is not a relocating storage allo- 
cator like the Macintosh; allocated blocks don’t move unless requested. 


¢ Support for a software exception handling model. This model is based on termination semantics (like 
CLU, Ada, and MacApp), and will support the semantics being developed for C++. All unusual condi- 
tions in Pink are expressed through this mechanism rather than through error codes. 


¢ Support for debuggers and handling of hardware (processor) exceptions. 
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Run Time Issues 


¢ The load files used for shared library files are currently Blue application (resource) files. These will be 
replaced by a native load file format when the Compiler Technology project (CompTech) compiler be- 
comes available (this compiler is being built by the Class group). 


e The design for how shared libraries are located is not complete. There will be “published” shared li- 
braries for everyone to use, but how library searching is handled when a developer doesn’t want to 
globally publish one is not clear yet. 

e The virtual function tables used for virtual function calls are currently constructed at compile time and 
live in the global data for a library. This means 1) new virtual functions cannot be added without 
recompiling clients, and 2) virtual function tables are not shared between teams. When the CompTech 
compiler is available, virtual tables will be constructed dynamically by the run time system, alleviating 
both these problems. 


e As mentioned in the ke ll probably become a kernel. ft 


hat direction over 


¢ The exception handli 
time, and will be in f 


its final form. It wilk# 
ch compiler is avail 


The Foundation Clas 


Pink provides a large: 


sral utility to programm 
the system. They inc e 


d.widely throughout 


° Aset of collection cla: li esa 
set of high level classes (Bags, Sets; : 
for those needing finer control (has 
structures are provided, such as directed 


cy control. 


¢ An abstract class which represents a stream ¢ 
streams and restr g.them from such strear 


as higher or arbitrary pre 


¢ A framework for concurrency control and recovery (Credence). These classes allow shared data to be 
updated in a way which guarantees its integrity. They can be used to prevent data from becoming cor- 
rupted due to software crashes or some hardware crashes. These will be used by the Pink file system 
and other components; Pink will have no “Disk First Aid” like applications. 


¢ Aclass which allows objects to be stored in files and retrieved by keys, which may themselves be 
objects (PsychoKiller). 


¢ Aclass which allows short unique identifiers to be assigned to entities in an extensible fashion 
(Tokens). 


¢ Aset of classes for implementing client/server relationships (Scream). This is widely used throughout 
the system to implement classes which do their work by communicating with servers. 
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Foundation Issues 
¢ Itis not clear there are resources to implement any of the proposed SANE extensions. 
“Operating System” Services 


Many of the services that traditionally would be provided by an operating system are instead implement- 

ed via shared libraries and server teams under Pink. These services include: ; 

¢ Aset of framework classes and servers for implementing device drivers. These include frameworks for 
SCSI, Nubus (or other expansion schemes), mass storage devices, video, serial devices, and ADB. In 
each case, new kinds of devices can be added by deriving new classes from one or more of the base 
classes supplied by Apple. In many cases, developers will not need to write their own interrupt code 
but can instead use that; . 


* A set of client classes, 
provide a common in 


large volumes, full § 
(as opposed to onl: 
resource forks). 


rnational file names, arbitrary file a 
are volumes), and file groups (a get 


e A mechanism fo# 
discussed above: 


e Anevent server for coordinating : 
also enforces the fundamentals of the us 
system. 


¢ A layer server which arbitrates screen real e: 
screen and syn izes drawing with scree 
within the ap 


“OS” Issues 


¢ Itis not clear yet whether alf'individual devices will be controlled by separate 
devices may be controlled by objects operating within shared teams. 


¢ The functions provided by Rainbow Warrior overlap somewhat with those provided by the Desktop; 
they need to be coordinated. 


¢ There is a major missing component, namely security and authentication services. This is necessary to 
guarantee the security of the local file system. Access to the file system, to certain hardware resources 
(such as mass storage devices), and to certain OS features (loading ISRs, creating physical segments) 
must be authenticated if the local file system is to have any more security than it does today. A recent 
survey stated that around sixty percent of all Macintoshes were used by two or more people, so this 
seems like a good idea. This issue must be resolved soon. A related issue is how to deal with people as 
objects in the system; this is needed for collaboration as well as authentication. 


e Another area which we must consider is system reliability. If Pink systems will be used as servers, we 


" may need some or all of the following features: storing information redundantly to protect against 
media failures (including disk mirroring), logging of soft and hard errors to spot potential problems, 


@ Registered/Restricted Pink System Architecture Monday, March 26, 1990 1.2-10 


some measure of fault recovery. Do we want to do these? Also for servers, we may want to allow vol- 
umes to span multiple physical disks. 


¢ Currently there is no strategy for dealing with power management, an important issue when running 
on future Pink-capable battery-powered machines. The key requirement is to be able to tell that the 
machine is “idle”, ie., no useful work is going on, so that it may be put to sleep. Since many teams and 
tasks will be running even in the idle state, we need to put a framework in place for extracting this in- 
formation. 


¢ The system boot sequence has not been designed yet. Pink may or may not be in ROM, but we will 
probably design a boot sequence capable of dealing with either eventuality (if only to aid during de- 
velopment) and of booting over the network. This work will commence shortly. 


¢ Rainbow Warrior provides a change notification facility, as do CHER and some other components. 
These need to be unified, or at least be expressed using a common set of base classes. 


The Graphics System 


g capabilities for 
pt™, and Render- 


The Albert graphics syste! 
Pink. It surpasses most 
man™, Here is a list of 


e Device and resolu 


e Complete 2D (3 
floating point co 


thicknesses, joi 
be added by dev 


ie, and/or framing. New: niques can 


¢ A large set of 3D primitives: lines, polylines, and curves; boxes, polygons, meshes, polynets, boxes, 
swept and extruded shapes, and 3D spline surfaces. 3D geometric collections: paths and surfaces. 

¢ Anextensible 3D rendering and viewing model that includes camera and light source modeling and 
many shading techniques. New kinds of rendering techniques can be added by developers, similar to 


programmable shaders in Renderman. 


¢ Anextensible 2D modeling framework which can tag objects with rendering attributes and transfor- 
mations, and includes the ability to create nested groups. 


¢« Anextensible 3D modeling framework which includes support for sweep and extrusion. 


¢ A graphics output device model which is extensible to support many different rendering techniques, 
including standard frame buffers, graphics accelerators, and spooling of graphics for printing. 
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Albert implements all these capabilities with a small set of abstract classes, among them MGraphic (the 
abstract class for modeling), TGrafBundle (object rendering attributes), several geometric classes, 
TGrafDevice (an abstract output device), TGrafPort (graphics context for rendering), and TMatrix and 
TMatrix3D (transformation matrices). 


Albert Issues 


¢ Itis not clear how to handle developer supplied extended rendering classes (e.g., for shading) when 
sending graphics output to a graphics accelerator or other external rendering engine, or when putting 
graphic objects into a document which may be transferred to another system. 


¢ Still to be defined is the architecture for handling buffering, compositing, sprites, and animation. This 
is needed to support the mouse cursor, and dragging of objects in front of other, animating objects. It 
would also speed window dragging and handling of updates by obviating the need for redrawing 
windows in all cases. 


¢ The architecture for tex ned. Font raster caching mu 


e The architecture ford CLUT output devices be defined. 


Application Support | 


Pink contains severa 1g applications. These are 
the Application frame : i inter ae work, which 
supports the Pink dé ipti DE ‘9.the system 
script facility. Thes s 


are similar to windows, except that ne forma he rather than a a collection. They also 
provide a framework for managing interaction. 


¢ A set of user interface components (windows, buttons, menus, scroll bars, etc.) built on the foundation 
and extensible by third parties. This also includes views for common presentation techniques such as 
tables of items and collections of graphics. 


¢ A framework for tracking user interface actions which includes standard support for tracking the 
mouse, for handling double clicks, and for dragging elements within views, between views, and be- 
tween windows. The dragging framework also provides a means for a dragged element to 
communicate with other elements it is dragged over. 


The two primary building blocks of the application framework are the responder, which is an object that 
can receive events, and the view, which is an object that can contain graphics and receive positionally di- 
rected events (such as from a mouse). Views are also responders; they are a subclass. 
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Events are usually routed to responders in three ways. Non-positional events, such as keystrokes, are sent 
to a specific responder associated with the current frontmost layer; this responder is called the target. Po- 
sitional events, such as mouse button down, are routed through the view hierarchy to the view which 
was under the mouse when the event occurred. Finally, events can be routed directly to a specified re- 
sponder. 


In addition to receiving events through the event distribution mechanism, responders can receive input 
directly from other responders. This is done through output ports, which connect output from one re- 
sponder to the input of another. Thus, responders can be hooked together in different configurations 
without having to write code to do so. This is essential to a user interface construction capability, like that 
being planned for the Hoops development environment (Pink’s native development environment, also 
being built by the Class group). 


Views can be thought of as virtual paper, and the view hierarchy as a mechanism for arranging those pa- 

pers to make a coherent interface Each view has ata minimum, a container (the view within which | it ap- 
pears when displayed), a pé iiaitier, a coordinate system (impleme ya tran: 
mation relative to its conta nd a boundary (which may b 
themselves when asked (311 
aries, any ancestor's b: Ff 


- 


an Albert 
, and are hidden by 


views in front of them. 


ction in progress. The 
acker provide support for 


based on the tracker object, which repre 
‘the interaction. Standard 


The tracking framewo} 
tracker encapsulates a 
mouse tracking and « 


The Document Fr 


The Pink document framework: 
standard Pink document model. In p 


¢ Collaboration: every Pink document bui 
laboration between users on that documen 


¢ Hypertext: 
al and can be) 
lowing a “hot link’ 
their own custom capa ilities. 


¢ Multi-level undo: like MacApp, CHER provides a framework for implementing undo. Unlike 
MacApp, CHER’s undo is multi-level; users can undo back as far as system resources permit. User ac- 
tions are logged using Pink’s recovery features, so users need not save to preserve their work from 
crashes. 


¢ Content based retrieval: CHER provides a framework for indexing and content searching, to allow 
documents to be located by content. 


CHER is at the heart of Pink applications because Pink has a document-centered user model: users deal 
with documents, not with applications. CHER provides a subclass of the application framework which 
knows how to deal with documents and knows how to integrate with the desktop. Applications are in- 
voked whenever necessary to perform services in a manner transparent to the end user. 
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The Scripting System. 
Pink provides a system which allows end users to automate repetitive tasks. It has the following features: 


* Scripts can be recorded, and the system watches to try to discern repetitive actions. The system uses 
these to try to generalize the actions the user has just performed. 


* Scripts are represented in a visual fashion similar to storyboards or film clips, to make them more ac- 
cessible than textual languages. 


¢ Scripts are universal; the scripting framework is integrated with the document framework, making it. 
easy for all actions taken by the user to be recorded and played back. 


Application Support Issues: 


this may become 

rt for sprites must be 

:waits Albert support. 
ant to add some kind of 


ring of views, and Albé 
le. Palette management for support of CLI ; 
for seen a view sizes and resizing viev 


e Classes for ex: 
been designed 


¢ Help support will be idtegral to the application framework, but we are waiting for a human interface 
design before designing the software. 


¢ Work on the scripting system is just underway, and many issues remain to be resolved. 
Text and International 


Initially, support for text on the Macintosh consisted of TextEdit (32K characters, plain text) and the Inter- 
national utilities (Roman languages). Since then, the Script Manager has been added to support non-Ro- 
man languages, and TextEdit has been extended to support multiple fonts and styles. Unfortunately, be- 
cause there is no support for sophisticated text editing and because the Script Manager is not integrated, 
every developer who wishes to support text must write their own editor, and most skimp on non-essen- 
tial features. Very few use the Script Manager because of the effort involved, and many do not implement 
all of the Macintosh human interface (the word processor I’m using to write this does not support “intelli- 
gent” cut and paste). 
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Pink provides extensive support for sophisticated text editing. It includes a text editing framework which 
supports arbitrary length text and an extensible set of styles. The text system supports sophisticated 
typographic controls, text flow across blocks, high quality line breaking, and more. The framework is in- 
tended to provide a highly functional base level of text support in Pink, as well as a toolkit for construc- 
tion of high end text applications (word processors and page layout programs). The goal is to prevent de- 
velopers from having to reinvent the wheel so they can concentrate on providing distinguishing features. 
The text framework can be overridden to provide such features (like footnotes or indices). 


The text framework works closely with the international classes so that all text manipulation is fully inter- 
national by default. Pink uses a 16 bit character set (Unicode) and is capable of handling multiple scripts 
with different writing directions and input techniques. Because of the integration between text and inter- 
national software, input of complex scripts such as Japanese can be done inline while editing. Pink text 
can take advantage of such sophisticated options as automatic kerning, ligatures, contextual forms, and 
optical alignment. Pink will support simultaneous use of multiple scripts within documents, and will be 
able to switch the “system” . ind controls) while running. 


slopers to build 
tting, text parsing, 
uch more control 
es, local rules (such 


In addition to text editing, 
worldwide applications 
and text searching cana 
over configuration; they: 
as time zones), number:! 


rk comes with utilities to alloy 


Text and Internationa 


Indeed, there are no Bass Unico 


¢ There are some problems to be resolved wi 
same issue as above for Albert custom bun 
chine?). 


pping out irrelevant word endi ig 
tomobile”, for example. . 


used to let a query fo 


Printing 


The Pink printing system is composed of several pieces which work together to provide a flexible and ex- 
tensible system. These are: 


e A framework for objects which can be printed, which helps them deal with pagination, page size, and 
other printer attributes. This framework has a set of useful defaults which allow most applications to 
print with very little work. 


¢ Aset of classes for characterizing printer attributes and print jobs. This includes user interface classes 
for presenting a standard human interface to select such attributes. 


« A framework for building print drivers, which lets developers define new kinds of printers with new 


-capabilities. This is similar to the application, document, and other frameworks in Pink: developers 
need only define the unique behavior of their particular printer. 
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* A spooling architecture which will do all printing in the background. 


¢ An architecture for dealing with scanners. This consists of a set of classes for use with CHER to allow 
images to be input into applications, plus a desktop scanner object (a driver). 


Printing Issues 


¢« We would like to support multimedia output (sound, animation, video) in the printing architecture. 
This is still under investigation. 


Time, Sound, and Animation 


Pink has a set of classes dedicated to timing and time-dependent media. These include: 


eee 


¢ A set of classes for tir 
of timing informatiog t advance in real time. 


rms can be used to per- 


Issues 


(responders and output p classes. The common 
ground needs to be determined (if there is any) and shared as a set of abstract base classes. 


¢ The animation and video architecture has not been defined yet. 
Networking and Communications 
The Pink networking classes provide: 


¢ A framework for implementing a wide variety of networking protocols. In some cases, these protocols 
can be mixed and matched. 


¢ Support for simultaneous connection to multiple networks (“multi-home”). 


¢ Acclass which represents a network resource, which can also instantiate transaction or streaming con- 
nections to that resource, independent of the network protocols used. 
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e A networking and communication component to the Blue Adapter, which emulates native Blue net- 
working services by calls on Pink network services. 


e A set of classes for accessing the capabilities of MCP cards which utilize the A/Rose kernel, to enable 
use of the many NuBus cards which use the MCP platform. 


N&C Issues 

e There is currently no equivalent to the Communications Toolbox defined. Something on the order of a 
TSerialConnection desktop object seems necessary to allow configuration of native Pink software. 
using serial connections. 


e There are human interface problems involved in mix and match protocols and multiple networks. 


The Desktop and Finder 


In order to meet its goal of 
cranny, Pink assigns the 
not just a window onto ¢ 
the “world” inside the c¢ 


tion of such concrete classes which can be usec 
volumes, folders, NuBus cards, etc.). Also natu 
classing any of the classes Apple supplies. 


y (e.g gs a printer into a “socket” in a wind: default printer 
for a document). The connection between desktop objects and potential users s of those objects i is made 
using the dragging and type negotiation protocol defined in the Pink application framework: a target can 
accept a desktop object if the protocol determines that they have a “language” (a type, representing a pro- 
tocol) in common. 


Developers will also deal with the desktop by creating desktop objects of their own: the example given in 
the principles section was of a TMassStorage object creating a desktop object to represent the raw device, 
and of the File System creating a desktop object to represent the volume or volumes on such a device. Be- 
cause objects find the desktop, rather than vice versa, the mapping of resources into desktop objects can 
vary widely across system components and over time. 


In order to increase the consistency of the metaphor, Pink discards some components of the Blue inter- 
face. Like Lisa, Pink uses a document metaphor; applications are only resources that need be present to 
enable certain kinds of documents to be opened and manipulated. The user opens a document, and does 
not (consciously) “run” an application. Similarly, Pink discards some File menu commands: New, stan- 
dard file, Save, and Quit. 
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New documents are made by copying stationery (the application itself could serve as default stationery to 
avoid the Lisa problem of throwing all your stationery away). Documents are saved automatically; rever- 
sion is handled by multiple level undo and “snapshots” of document versions. Standard File functions 
are handled by the Finder; users will not miss Standard File as long as all the shortcuts (and speed) it pro- _ 
vides are in the Finder too. Quit is superfluous since users work on documents, not in applications. Each 
document will appear separately, rather than all documents of a given type being lumped together if 
more than one is open. When and how application code runs is determined by the system, not the user. 


Finally, the Pink desktop will reduce the distinction between desktop objects and data. Desktop objects 
can be dragged into containers, and in Pink selections can be dragged between documents. We would 
also like to be able to drag selections into containers (perhaps creating new documents) and desktop 
objects into windows and documents (as in the printer selection example above). 


Desktop Issues 


‘unac- 


* Ideally, file system ope ; 
the file sys- 


ceptable from a perfort 
tem to notify the des 


he desktop to ensure consistency. Th 
ase a scheme would be neces 
changes. : 


The handy-dandy Ag egotiation Protocol™: 


i peng and’ Pype n designed yet (al- 
ation part has been implemented for CHER}. 


can be tuned for experi- 

eti - needs of experi- 
to. change bit 

itors 


the Chooser can be 
assed altogether: 


pervasively as our user e ; 
The integration of the Standard File:k 5 i can 
be done. 


* The design of the desktop classes depends i d le- 
sign of the general Pink human interface. T : 


(custom) imp 
well. This is t 


¢ The pervasiveness of the desktop means that it will permeate every corner of Pink, and thus affect the 
design of many components of Pink. However, the desktop classes are only now being designed and 
implemented. 


* Once the desktop classes are available, there are an awful lot of desktop objects and utilties which 
need to be designed and implemented. All functions that are currently handled by Chooser, Control 
Panel, HD SC Setup, Font/DA Mover, ad nauseum, must be built. This is a lot of work. 


Adapters 


Pink is designed to allow foreign operating environments to be emulated concurrently with native Pink 
applications. These emulators are known as adapters. There are two currently being planned: 


¢ The Blue adapter will allow Pink to run existing Macintosh applications and some subset of other Blue 
software (probably DAs, cdevs, and some INITs). The technology used will be very similar to that in 
' A/UX 2.0; the major difference is that unlike A/UX, Pink has a native video architecture and cannot 
use the Blue model unchanged. In addition, some measure of data exchange between the two worlds 
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will be possible: at least clipboard and file import/export, and possibly some connection with CHER. 


e The UNIX adapter will allow some subset of applications written for UNIX to run under Pink. The set 
of applications which run depends on what UNIX applications, and thus what UNIX features, we con- 
sider important to emulate. The goal is to let applications which use standard System V, BSD, or 
POSIX interfaces to run, and also to support such common UNIX accouterments as X. It may even be 
possible to support one of the application binary interface (ABI) UNIX standards and thus run existing 
binaries, but given the projected installed base of Pink this may not be necessary. 


Adapter Issues 


¢ The technique for handling graphics in the Blue adapter has not been decided. Allowing QuickDraw 
to continue to draw to the screen guarantees pixel perfection, and the Layer Server was designed to 
allow multiple rendering systems. However, this doesn’t work well on devices which are not a 
multiple of 72 DPI, and it breaks down completely for graphics accelerators. Under Pink, a graphics 
accelerator card will be | It also doesn’t work for devices wii scaling 
transforms (like rotation 


uestion. DAs, cer- 
‘ap up Blue video and 
s not guaranteed by 
make this much easier. 


¢ How much software t 
tainly, probably some If 
disk drivers (by far the most important) to make them run under 
any means. Rewritifig drivers is a pain, but the Pink I/O framew 


e i (not to mention the re d to.implement it) have 
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Pink Human Interface 


Pink Human Interface 


e Simplifies what is 


¢ Adds what's new 


« Restores the fun 


Lee Honigberg 
Frank Ludolph 
Annette Wagner 
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Introduction 


Pink continues the Apple tradition of innovative, attractive, easy and fun-to-use human interfaces. 
The Pink Human Interface also has the following goals: 


¢ Similar in style and appearance to the current Macintosh interface but more refined and 
attractive. 

Integrates and simplifies existing Macintosh interface features where appropriate. 3 
Avails users of new technologies in Pink. 

Designed to support groups of users, yet retains its focus on the individual. 

Run on existing hardware, but designed for the attachment of additional interface peripherals. 


ee © @ @ 


This 
design principles. This is 
describes the architectu 
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Extending the Macintosh Design Principles 


The user interface design principles enumerated and detailed in the book “Human Interface Guidelines: 
The Apple Desktop Interface" will be applied to the Pink user interface. Experience and changing 
technology suggest that some modifications are needed. Pink also adds two additional guidelines: “It 
works the way you do” and "Fun to Use.” 


Each of the guidelines is reviewed below. The boldface sentence at the start of each section summarizes 
the book's definition. ; : 


Metaphors from the real world 


ake ern 


Use concrete metaphors:and 
computer environments. 


wik User Interface is 
t and so it is perfect 
lizing to the physical 


Lisa and Macintosh usé 
the physical world. T 
to the extent that the: 
world metaphor it 
degradation of the i 


xpected that Pink will be able to incorpor 
face than we have experienced in Blue. 


Pink will layer the 
paper’ world) on 
workshops, and e 
exist side-by-side 
physical world. 


The use of a metaphor does not imply 


be extended when clearly appropriate. 
familiar and plausible. 


It works the way you do 


Supporting flexible working styles is not the same as giving users a zillion options. While large 
numbers of options theoretically support extensive personalization, they also increase complexity. 


The Pink Human interface extends Blue to include user-centered mechanisms to support projects, 
sharing, network access, and communication. 
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Direct Manipulation 


Users should be able to manually interact with the metaphor rather than having to 'talk' to it via the 
keyboard. 


The most important factor affecting the quality of direct manipulation in Pink is the physical 
similarity of manipulations in Pink to their real world counterparts. It is best to maintain a direct 
correspondence between the real world and Pink's virtual world. For example, moving something in 
Pink should always be done by the user moving the mouse, rolling a track ball, or other comparable 
physical displacement movement. 


The limited capabilities of the hardware may make the implementation of a physically corresponding 
action impossible and require the creation of controls in order to support a needed operation. These 
controls should, when possible, simulate real world controls that are used in similar situations. 


Pink is designed to ma 


stitute I/O peripherals, e.g. st 
track ball, that are mor : Re 


See-and-Point 


tldn't have to remember 


is easier to 
ulation of 


“the things they see an 
titute for good interface design. 


“Step tasks. 


However, on-liné 


Feedback and Dialog 


Keep the user informed by providing immediate feedback. 


Feedback and dialogs are the way the computer shows the user what is going on inside itself and across 
the network. Feedback must be immediate for direct manipulation interactions to work well. Long 
tasks, which can potentially run concurrently, will use animated feedback to indicate actual progress 
and anticipated completion when possible rather than a “time is passing" wristwatch. (How long do 
you look at the watch before deciding that something is wrong?) 


Pink's multi-tasking will allow users to do other things while long tasks proceed. Feedback and abort 
mechanisms for these ongoing tasks must be accessible but not disruptive. 
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User Control — 
The user, not the computer, initiates and controls all actions. 


Under Blue users must sit and wait for a long operation, e.g. initializing a disk, to finish. The only 
thing they can do is to cancel the operation by typing CMD-PERIOD (if supported). Users are also 
arbitrarily interrupted by network related tasks (mail applications are notorious for this). In Pink, 
users will be able to immediately select and use objects that are not part of the long operation. 


The user, not the computer, controls the positioning of the pointer, icons, windows, and scrollable 
content. When it is necessary for the computer to scroll to bring the selection into view during an 
operation, it is best done in a way that helps users to quickly reorient themselves by minimizing change 
and/or maximizing the surrounding context. 


Pink extends the concept 
bureaucratic, system-cen: 
the delegation of a few ff 
on the network are del 


ce objects 


Forgiveness provid 


ds the single level 
undo in Blue toa 


Blue so less effort and understanding is re 
that standard interface elements will be more 


a ie mann 
The Pink in: 
appropriate. 


mechanisms for t 


We cannot anticipate nor support every developer's needs and desires in the future. However, Pink will 
provide a toolbox of basic interface elements that can be combined to support future functionality. 


Many applications in Blue have added invisible commands to the interface, usually in the form of 


modified mouse-clicks, using the COMMAND, OPTION, and SHIFT keys. Pink assigns standard meanings to 
these keys, e.g. ‘constrain’ or ‘do’. 


Perceived Stability 


Users feel more comfortable in an environment that only responds to their actions rather than changing 
randomly. 


Whereas Blue initially supported a single thread of execution, the user's process, and was more recently 


extended to include background tasks such as printing and mail, Pink must provide users with a sense of 
stability in a heavily multi-tasked environment. 
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WYSIWYG 


There should be no significant difference between what the user sees on the screen and what eventually 
gets printed. 


Pink's resolution-independent, anti-aliased graphics (Albert), and better display hardware will 
enable the appearance of a document on the screen to correspond even more closely with the printed 
appearance than in Blue. 


Pink also extends WYSIWYG to include sound, video, and animations that can both be manipulated on 
the machine and output in the form of a recording to video and audio tape. 


Aesthetic Integrity 


Visually inconsistent dis] 
Objects in Pink will has it, sixteen color 
provides the design b 
color. 


windows and common 
ild not be considered the 
ects, e.g. the 
erformance 


Work is proceeding ana 2 1/2 D, front-light model. These two pi¢# 
interface objects ar shots of the current state of developm: 
finished product. ( a 
transparent drop § 
reasons. 
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Fun to Use 


The Lisa and Macintosh User Interfaces w 
demonstration were virtually compelled to: 
many of which are embodied in the other gui 


ing. Peopl 
es. All of the ow, 
rable experienk 


¢ visible what can be/was d 

* efficient, little wasted moti¢ 

° very resf “adjustments are } 

* obvious edback shows what is happening 

* safety © 2cOver from mistakes 

* sense of contro S$, machine responds rather than prompt 
¢ novel stimulation 

e 


improved results 


On the negative side, anything that requires extra time and effort will be irritating. This means that 
many things that make games interesting, e.g. non-obvious strategies and high failure rates, are 
inappropriate in Pink. 


The only way that developers can tell if their products are enjoyable to use is to watch all kinds of 
people use them. User test, user test, user test! 
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A Pink Interface Proposal 


This document attempts to describe how the Pink system will look to the user. The purpose of the 
design is to give us something to criticize. It should function as a "strawman" — an early plan set up 
with the intention that it should be knocked down. 


Describing a user interface is tricky business. My approach will be to begin with the existing Macintosh 
interface and pare it down to a simple core. The next step is to add (hopefully) clear and simple 
interface parts to represent the functionality that was stripped away as well as the new functionality 
that defines Pink. In other words, the design requirements are: 


1) Clean up the old stuff 


2) Provide an interface for the new stuff (e.g. collaboration or multitasking) 


ty behind the design prese 
mplex interface is ultimate 
ict all the cases that nee 
manipulation interface. At the 


A few comments mig 
extremely wary of tryi 
implementation. It's ju 


It with given the 
re, some large scale 
i user comprehendible 


ke the interface consistent and also to figure.6 


simplest interface given 


Second, this design : give 
uestion we begin 


thea minimalist interface. I have: 
the two design requ ov 


Third, this design 
or elsewhere. That's ok 


Finally, what you are reading represen 
with "***", take the menu command nam 


With all that in mind, please read on. 


Macintosh:A 


Picture if yo 
Pretend for just'ar 
is to add the functiona 
and simple Finder to sta 


Add to this minimalist system two features from NuFinder: Keyboard Navigation and the "Find..." 
menu command. Keyboard Navigation allows the user to type the first few letters of a filename to jump 
to and select that icon in the frontmost Finder window in a manner similar to the scrolling list in the 
Standard File Open Dialog (the arrow keys also work). The "Find... / Find Next" menu commands very 
quickly search all mounted volumes for a filename, opening any necessary windows and selecting 
matching files. These features are needed because the Finder is going to be used to represent lots of new 


kinds of information, and the better it is at finding, the easier that will be. 
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The New Layering Model 


Menubar 


The menubar stays at the top of the screen. It might be a user preference to place redundant menubars at 
the top of each topmost monitor on a multiple monitor system. ; 


Document Layers 


. 


The first change is to the window layering scheme. Instead of MultiFinder's one layer per application, 
the rule is one layer per document. In addition, each Finder window acts as if it were in it's own layer. 
So a possible window ordering from front to back might be: 


- So if the user clicks on 
is "My Budget", then 


the document the 
are ordered with 


Under a menu labeled "Windows" (or per 
side of the menubar) is a list comprised 
documents (arranged alphabetically). If the 
"Hide" command. The "Hide" command wi 


cation. So, f6: 


My Budget 
My Novel 


Hide "Letter to Mom" 


Like the current Apple menu, small icons appear next to each item in the list of documents to convey 
more information and a check mark indicates the frontmost document. 
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The Apple Menu 


The Apple Menu contains the "About" menu command followed by a list of tools and documents to which 
the user wants quick access. The mechanism for customizing the Apple Menu is described later in the 
document. For the moment, the Apple Menu might look like this: 


About Excel... 
Alarm Clock 
Calculator 
Puzzle 

Random Thoughts 
Doodles 


Again, small icons appe icate type. Note that the documents Rane 
Thoughts" and "Doodles f : pple menu is 
open, it's name remains in i i 


Fast Switch 


16 front. A command key 
fen nicer would be some 
inder windows to the front 
i lable, prepare the 


Choosing "Finder" fr 
equivalent would bs 


the Windows menu brings all the Finder 
his will be a fairly common 


Placing icons on the desktop in the current si 
under other windows. Second, given a file 
disk that file is actually stored. We can solvé I 
ument windows so that the right edge of’ 


desktop as the 


The New D tion Scheme 


Stationery 


New documents are created using the long familiar stationery pad. Double clicking on a stationery pad 
results in a quick animation to show an untitled document sliding off the stationery pad. This icon 
immediately opens into window named “untitled”. The user can name the document by choosing 
“Rename” from the File Menu. (An option in the naming dialog makes this document into a stationery 
pad itself.) 


The user can also name the document by going back to the Finder while the document is open, selecting 
the icon, and typing a new name. Just as the titlebar in a Finder window changes dynamically to reflect 
a new name as it is typed, the titlebar in a document window changes dynamically to reflect the new 
document name as it is typed. The rule is that an open document window is always in sync with its 
finder icon. If the user moves the icon of an open document into a different folder, the document is 
simply now in the new folder. 
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There continues to be a "new" command in the File menu of applications. It creates a new untitled 
document from the stationery pad that was used to create the current document. Double clicking on an 
application icon will open a window containing, among other things, a default stationery pad that 
cannot be deleted. 


Versions 


Document saving is handled quite differently than it is in the current system. Documents are always 
saved to disk to within an operation or two. It's as if the user were constantly hitting command-S. 
Multiple level undo and versions will (hopefully) replace the back tracking allowed by "Revert to 
Saved" in the current model. 


Undo and Redo step back and forth through the operations in a single document. What exactly is 
defined as an operation is left up to the application, but Apple should offer suggestions at some point 
about questions like "does, ition?" It seems as if the only way toa ese 
questions is through exp : 


state as a version 
ose to revert to the 
ourse, undoable. (It 


At any time while ed 
(“Checkpoint,” from th. 
previous version ("Previo: 
may be a user option té er 


The Get Info Box i 
each version. A ve 
select a past versio 


with the date and time of 
a snapshot. The user can 


1) name 
2) delete: 
3) 


Note: Although at first glance it might seem 
Get Info Box and onto the desktop, I think i 


“create a real ¢ 
the Get Info 


Version Info 


(**"Does the user get the undo history for old versions?) 


Summary - The File Menu 


Suppose the user had just opened a document from a stationery pad labeled "Pink Letterhead." The 
File Menu would look like this: 


New "Pink Letterhead" 
Rename "Untitled" 
Close "Untitled" 
Checkpoint 

Previous Checkpoint 
Print 
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Tools - Applications Without Documents 


There are some icons the user will open which do not yield documents. Call these things tools. Into this 
class will fall the desk accessories and control panels of today. The rule is: there are no mysterious 
chunks of code that don't open into a window. 


Multitasking 


To understand what multitasking will do to the system, join me in the following thought experiment. 
Picture a simple animation application. There are two squares in a window. The user selects one and 
chooses "Spin". The square starts spinning. Then the user selects the other square and chooses "Spin". 
Now both squares are spinning -- voila — multitasking. This is the kind of stuff my mother could 
understand. What is it about this scenario that makes it so easy to grasp? There are multiple tasks, or 
activities, going on simultaneously but each one is confined to a single object. The rule, th for 
multitasking is this: Boe 


user could see, say, 
document is only doing 
asking objects within a 
ty of multitasking objects 
ocus of this discussion, so 


What is an object? In 
three documents, each: 
one thing at a time. ! 
document. So the a 
with the spinning sq 
assume that the objé 


e) 


& g- 
Jepending on the application, there may al¢ 
ation application above is introducing a fin 
However, what goes on inside docume 


What does all th 
always be able to 
always always ys besae 

dialogs in the current system will 
alerts will be associated with documert 
connected with the document to which 
switching to a different layer. Finally, th 
busy and this will appear in the icon, in the: 
document names appearing in the Windows m 


consider a spreadshee recalculating. Three things 
command in the File menu (remember, menus are always accessible). 


1) Disable it. The "Close" command (and almost every command) is grayed out. 

2) Leave it enabled without command queueing. When chosen, the "Close" command would 
cancel the recalculation (reverting the document its state before the recalc) and immediately 
close the window. 

3) Leave it enabled with command queueing. When chosen, the "Close" command would close 
the window after the recalculation is done. 


In the spirit of making decisions, assume that the rule is this: whenever possible leave a menu command 
enabled with queueing (3), and when that can't be done, disable the command (1). 


Status Window 


The "System Status” tool opens to show a list of currently busy documents and tools and what each one is 
doing. A task would be listed in "System Status" only if it is going to take longer than a second or two. 
If possible, some indication of estimated time remaining would be nice. 
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+ + 


Cancelling a Background Task 


Any task can be cancelled from the "System Status" tool. Also, the task in the frontmost document or 
tool window can be cancelled using command-period. Lastly, the user can select the icon for a busy 
document or tool and cancel the task, again using command-period. What happens to queued commands 
when the current task is cancelled? They get cancelled also. Cancelling always returns an object to its 
non-busy state. 


. 


Transparent Multitasking 


Finally, some parts of the system may use multitasking but never tell the user. For example, the Finder 
windows preflighting described above would probably be done using a separate task, but the user will 
never know about it. The.rule is: behind the scenes.uses of multitasking are never noticeable.to: user. 


(Of course -- if they were notic e behind the scenes, would the 


Examples 
Copying files - *** 
Printing - *** 

Formatting disks 


Notification, 


ad 


The Network 


On the right side of the desktop, beneath #1 
labeled "Network." Opening this yields a wi ; 
"File Servers". ‘Ehese. folders and their conte ings. ‘work 
behaves simil fi ‘ , 
moved to the n arrang ings a in i change 
the view but ¢ change. ¢ id is that 
all network thir : ¥..winde 

Network icon is determin :: Way people and equipment are connected: real‘world. The user 
can't drag a printer from inside the Network icon to the trash and forever lose that printer. The user 
can't move a fileserver from one zone to another. Network things would get a different "look" than 
ordinary file system objects to convey they fact that they cannot be edited. 


Note: The following scheme is based on the assumptions that zones are a fact of life. 
Copying Network Things 


Since the Network works like a read only disk drive, dragging a network thing out of a network window 
makes a copy of that thing. So I can drag a person, a printer, or a file server to the desktop or to any of 
my own folders. The copies of network things work just like network things found inside the Network 
icon. 
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People 


Within the "People" folder, organized by zones, are icons for other users on the network. Double 
clicking a person gives useful information about that person such as their phone number or office 
location. People icons don't do much by themselves, but are used in other parts of the interface (such as 
mail) to refer to other users. See Figure 1. 


" File Edit View Special ‘i 


= Crimson Permanent >= && 


O 


Printers 
(7) Etherknott 


Printers 


d.by zones. In a giver gone, the view 1 
r Kind. With some'settip by a system adm 


Printers are als 
icons or sorted 
present printer 


The user can print a document by dragging its icon to a printer. The documen g 

quick animation with the printer icon, then the document goes back to where it was dragged from and 
the print dialog appears. The print dialog, like most good Pink dialogs, should be non-modal. With 
the fast switch to the Finder described earlier, printing by dragging documents to printers should be 
fairly painless, but some mechanism for printing from within a document is still necessary. This 
requires defining a default printer. For more details on how that is done, see “Print Shop" below. 


Double clicking on a printer opens a window showing printer status. 


File Servers 


Once again arranged by zones, icons for file servers appear inside the Network icon. Call these icons 
“server stubs.” Double-clicking on a server stub mounts that server. Server stubs work very much like 
Quick Mount documents on the Mac today. Although it would be nice to just open the fileserver's 
window directly from the stub icon (instead of mounting the server), this leads to several gotcha's that 
are best avoided at this point. No doubt there is a better solution than the one proposed here (a 
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mysterious chunk of code which doesn't open into a window). Like people and printers, the user can 
drag a server stub out of the network icon and leave it on my desktop or put it inside a finder window. 


Double-clicking on a server stub brings up a password dialog box for file servers with controlled access. 


Other Kinds of Network Things 

Other devices on the network also appear inside the Network icon. 
***How do they work? 

Modems 


Scanners 


Direct Manipula 


The traditional menu 
addition, these editin 


‘they do today. In 
fviost users are familiar 
te prototype illustrated 
bility" can be added to 
documents. The general 


spreadsheet cells, s 


d animation clips, and most kinds of di 
rule is: dragging mo j 


abject. and option-dragging leaves a 


puree. 
that window's porthole, the objé 
The user can continue dragging this*4 
porthole of any other document which ur 
clipboard icon into the porthole of second di 
object can be placed as usual. If the user | 
another document, the clipboard icon rem 
er can leave as many o 
n-dragged) into the 
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Text Doc 


justice: 


AAMAS nenenananne? 


We the people, in order to 
form a more perfect union, 
establish , insure 
domestic tranquility, 
provide for the common 
defense, promote the general 


Linking 
Scripting 
History W 
*** Connection to System Status Window? 


Post-its 


Post-its or annotations are kept very very simple. An “Attach Note" command is added to the standard 
edit menu. The user can attach an annotation to any selection. A small standard icon appears in the 
document. Double clicking on it brings up a window. There are buttons to record and playback sound, and 
a simple type-in text field. The text field would be limited in powers to approximately that of 
TeachText. 


Filling Out Forms 


The designs for the next few pieces of the interface apply a new technique to expand the use of direct 
manipulation. In the current Finder, direct manipulation (or dragging) of icons representing files has 
two characteristics which make it successful: First, it always works. The user doesn't have to know 
any special rules about where dropping an icon is allowed and where it isn't. Second, placement of icons 
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by direct manipulation always means the same thing -- where a file is stored. In fact, the place where 
this meaning is overloaded is exactly the place where users get confused. The System Folder in the 
current model has all kinds of additional semantics and as a result it has become somewhat of a 
sinkhole in the Macintosh interface. 


It's time for a new widget. If dragging icons from the Finder is going to be used to represent some of the 
new functionality of Pink, users need to know when that dragging is appropriate, which icons go where, 
and what the dragging represents. The mechanism for all this is called (for lack of a better name) 
“filling out forms". The idea is that in order to complete a task which involves something represented 
by an icon in the Finder, the user drags the icon into the appropriate blank space on a form. The outline 
shape of a blank space in a form matches the outline shape of the kind of icon that goes in that space. 
Most forms have the magical property that there is always a blank space available. When an icon is 
dragged into an existing blank space, that space is filled and the eternal blank space moves over one. 


In addition to indicating when draggin 
represented by Finder i S 
the form nor is it copie 
in blanks is the only wi 
System 7.0. 


g is appropriate, forms are the mechanism for referencin 

As: #d into a form, the thing it represents is-nof: 
‘fled in blank is a reference to t] 
things. There is no gener 


The following example 


e used to solve a whole series of interface 
; rfaces that follow after 


rface for sending mail in some detail. M 
s technique. 


Fill-in-the-blank form 
works through the it 
this section also.us 


An Example 


So we 


The easiest way f 
e-mail across th 
to at least two kinds of Finder 


1) the recipients of the mail m 
2) any files to be enclosed with 


Finder can be 
blank, the bla 


type-in text fiel ‘t 
enclosure had been plugged in, ‘King "Send" would send the mail. Cl 
allow the user to save this ment or discard it, just like any document. 


Notice that dragging a person or file into the mail form is not the same as dragging an icon into a folder. 
Dragging an icon into a blank on a form is a reference to the real thing in the file system or the network. 
So the icon for the enclosed file “Budget Doc" does not represent a copy of that file, but a reference to 
that file. 
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€ File Edit View Special % 


Mail Stationery 


% 


Poor eseeeceees, 


Here is the plan... 


rchitecture 


Summary 
The blank on a form tells the user three things, and these hold true for all blanks on all forms: 


1) that an icon of a particularly kind can be dropped here. 

2) that dropping an icon here has semantics other than the standard Finder semantic of 
rearranging my file system. The semantics are stated right there on the form, probably as 
text. This should visually distinguish a window containing a form from a standard blank 
background finder window. 

3) that the icon being dropped here is not being moved or copied but referenced. 


. 


Details 


How does the user remove something from a form? . 
Drag it to the trash, or per: pasted t: ide:the window. 


Can the user drag an ic ted form and onto the deskto 
No. Since being in a foi reference, and since fo 
references are allowed ut of a form onto the 
windows. . 


ly place where 
into Finder 


Can the user drag an:i¢on out of one form and into another? 


Yes. 


Can the user rena 
No. 


Can the user ge real 


thing? 
Say no, for now. 


windows. 


Where exacts 
Inside docum 
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Groups of People 


Opening the Group stationery pad gives a form similar to Figure 5. The user successively drags in 
people icons to create a group. Click on the close box, select the untitled group document, and name it. 
Group icons resemble people icons, and can be dragged into any blank that is expecting people (including 
the group form itself — groups of groups). Groups are first order objects just like people, so the user can 
duplicate them, mail them around, etc. 


eee 


C] = = ~ Untitled Group 


Group Members: 


Collaboration 


There is no design y : up the 


document for checking in and che 
There is no design yet for whole screen sha 


To begin a same-time same-document co 
(perhaps stationery, so collaborations could , : i fe ared 
and the people te:collaborate with and click the:€ ton. This ope fied 
documents if t st.already open and te i ft sted 
user decides re. collaboration..waid 
computer. Th i 
Quickmail or th 
the phone as well 


ition is a typing free for 


inframes. Hopefully the co. contact over 


Once the collaboration has started, how should pointer passing work? This is undetermined at this 
point. Experimentation is the only way to find out. 
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Notably and intentionally missing are any control enforcing mechanisms. Everyone in a collaboration is 
on equal footing, and there is no access privilege scheme. If a user is afraid that collaborators will mess 
up a document, then that user can make a copy of the document before entering the collaboration. Also 
intentionally missing is any kind of whiteboard. If users want to share a drawing space, then they can 
open a draw or paint document. 


0S Untitled Collaboratio 


Collaborators: 


Documents ta Share: 


[tomect_] 


Project Lists: 


Projects are a means f 
file system. Projects could be o 
satisfy the needs that resulted in alia 


Fill out a form. Connection to Projector sty 


‘the printer 
set a default 


Users would dr 
that is used by the:Prin 
color printer, a default 


nd from within a document. It 
nd white printer, a default legal size paper pr 


*** Where to put page setup options and what is the relationship between documents, page setups, and 
printers? 


All the Other Stuff Now Found in the System Folder 


The plan is to have no magic places in the file system. Instead of moving a screen dimmer INIT to the 
system folder and restarting in order to get it to work, the user would double click on the screen dimmer 
icon to open a control panel with an on/off switch and perhaps some other controls. Switch the screen 
dimmer on and close the control panel. In other words, the two rules are: 


1) It doesn't matter where the user puts an icon. 
2) Every icon opens into something. 
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However, when icons can be grouped together with some higher meaning, then the device to use is the 
previously mentioned "Fill in the Blank". 


Here are some examples: 


How might the user customize the Apple menu to contain the Calculator, Alarm 
Clock, and nothing else? 
Double click on the "Apple Menu Shop" icon and fill in the blanks. See Figure 7. 


How might the user preview the font "Galliard” (a la Keycaps)? . 
Double click on the icon labelled "Galliard" to open a window showing the font 
mapped onto the keyboard. 


How might the user add the font "Galliard" to the system? 
Double click on the "Font Shop" icon and add “Galliard" to the system fonts form 
by dragging in theicon 


Calculator Alarm Clock 


nents: 


independent pa ‘of concepts which ma 
I can imagine sitting hrough the details of the 

described above without reverting to ‘that completely fuzzy state of mind in' which none of the interface 
is defined and everything depends on everything else. Which is also to say that these are the pieces 
which I haven't thought much about except to suggest that they sure would be nice. Everything in this 
section deserves a "***" for lack of content. With that in mind, here is a grocery list of new interface 
things: 


Mail 


Outgoing 


See Figure 4 and the description above (in the section describing forms). 
This represents the simplest case. Other fields, like "CC:", might be revealed using the progressive 


disclosure device described below under "New Widgets for Applications." Since mail forms originate 
from a stationery pad, there should be a mechanism for creating custom letterheads. 
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Incoming 


Add a mailbox icon on the right edge of the desktop. The icon changes appearance when mail arrives. 
Double clicking on the icon opens a window containing incoming mail. 


Personal AppleShare 
Users would open a File Sharing tool and drag in people (or groups) and file system objects to be shared 


(a disk volume, a folder, or just an individual document could be shared). Those people would then see a 
server stub in their Network icon. 


%* + % 


New Widgets For Applications 


Here are some user interface:sup 


riepackages:Apple provides to applications in addition 


Progressive Disclos 


beginning users. The 
disclosure. Applications 
ch between the simplest 


mailbox flag in the 
would have a stan 
version and the co 


rm Clock DA is the perennial example of | 
widget to put in dialog boxes so the us 


In addition to upe : ‘came a. 


The current system has a standard color 
provides a standard font and style picker. 


ple 


Standard (and Replaceable) Dictionary and Thesaurus 


Provide a mechanism and interface so that the same dictionary can be used across all applications. 


Dialog Layout Rules 


Decide on some set of rules for the size, spacing, and arrangement of buttons in dialogs and give 
developers the tools that make it easy to follow those rules. 


Content Based Document Retrieval and Filtering 


Fill out a form using a graphical query language. 
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Smart Icon Cleanup 


Take a better guess at what the user is trying to place in rows and columns. Make sure icon names don't 
overlap. 


Smart Window Placement and Dragging 


It seems as if there is some set of rules for usually doing the right thing when dragging windows. For 
example, if there is only one document from an application open, then it probably makes sense to 
maintain the relative positions of satellite windows when the document window is moved. 


System-wide tiling or stacking of document windows might be done through a universal menu command 
in the Windows menu 


f the document. 


Preferences 


It is unclear as to 
a document, or wi 


Help 


Bubble help and/or procedural help. 


Backup 


Connection to ve 


Quiz 
If this was at all a coherent description of a reasonable approach, then. given a problem, you, the 
reader, should be able to see a solution which fits the model. And your solution should be similar to 
mine. 

So here is the problem: 

Design an interface for starting the Screen Sharing collaboration. The user needs to connect to one other 
user. (Don't worry about all the pointer passing conventions once the connection is made.) Design the 


interface for making the connection and ending the connection. 


See Figure 8 for the answer I was looking for. 
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C= Screen Sharing Tool 


Users to see my screen: 


yi? 
sedi 


Seecccccones o> 


Double click on the "Screen Sharing 
Tool" to get this window. Drag in a user 
and click “Connect.” 


Figure 8 
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The Architecture of the User Interface 


[The following has not been widely reviewed and the reader may find it incomplete and/or 
idiosyncratic. Reader's comments are appreciated.] 


The architecture of the Pink Human Interface lays the foundation for everything involved with the 
user's interaction with the Macintosh. Based on a real world metaphor, enhancements to the original 
Lisa/Macintosh architecture, and an extended “every-user” model, the Pink Human Interface 
Architecture is a broader and more general architecture that supports current useful extensions to Blue, 
anticipated Pink extensions, and, hopefully, most future unexpected extensions. 


The Pink Human Interface Architecture provides a systematic basis for designing all user interactions 
with the machine. Without..a..clear..comprehensive architecture, an interface will be« littered, 
inconsistent, and disorg: 


arr Interface, object, 
eractions supported 
nd their operations, 


This section contains 
operation, and interac 


eneric objects, operati: 
Varchitecture, that would detai 
sary p. Also, it does not provide e% 
e to be developed over time and involve 
implied from the architecture and the ff 


what follows is an 
interface - that will. 
that model can be e; 


Object 


Objects are the { Ypresent 
things in the wo 208! ; i i 
the objects are the made-up things 
scrollbars. 


There are four characteristics that descri 
interface. All objects have, in varying degrés 
and Macintosh/Blue defined objects that coul 
the objects rather..than the characteristics 
HyperCard sg Otations, and alia 
characteristi tai ; 


Behavior | 
Behavior is what things do, how they act. All objects appear to the user to have behavior. Even 
documents that have no code in them exhibit behavior when they are moved about (Finder code) or 
opened up and edited (application code). 


Lisa and the early Macintosh considered only one kind of behavior, built-in. Experience and technology 
show that there are more aspects of behavior that need to be considered: 
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* built-in non-modifiable, except via preferences, comes with an object 
¢ system-based uses system-supplied behavior when possible or overrides with built-in. 
* component non-modifiable functionality that can be added to an object (may have 
preferences) 
¢ script user-modifiable functionality that can be added to’an object (may have 
preferences) 
¢ dependent may vary by user, time, situation, editing vs. run 
* cooperating the behavior of one object may trigger the behavior of another 
¢ external behavior that is applied to other objects, e.g. move and delete; all the above are 
‘internal’ ; 
A task denotes the execution of some initial behavior and the behaviors it triggers. The current Pink 
position is that an object can only exhibit one behavior at a time, i.e. one task per object. The 
consequences of this position are under consideration. 


Content 


Content is the informa 
text characters, graphi 


‘composition of other obj 


atomic Objects are 
mies, and behavioral com. 


While the Lisa and thé:@arly Macintosh considered many of the aspe veral were not. 


¢ object relativ ize and creation date 

¢ behavioral 

* user task 

* presentatio 

* view-speci 

* app-speciff 

* system-supp : possibly 
¢ kind text, graphics 

¢ organization sequence, paralt , spatial 

* medium paper (page, sheet;: ti-media 
¢ dynamic changes with time, sit 

e shared multi-task access, acce 

* versions multiple snapshots ar 


Connectio 


Connections ing 
between the obje 
spreadsheet, frames in‘a'video si 7 
form of connection e.g. documents in a folder or pictures in a document. More comei forms may require 
computational support e.g. cross references, picture-to-text (to keep them on the same page), 
spreadsheet formulas, and filters. 


Objects are responsible for supporting connections from the outside to internal objects. The connection 
may be maintained by either unique id or attribute matching as appropriate. 


A connection may be represented by a concrete object (explicit) or not (implicit). Examples of explicit 
connections include links, aliases, annotations, and filters. Examples of implicit connections include the 
document to app (document type), cross reference look up, and containment of documents in folders. 
Explicit connections are objects in their own right and can have their own content, behavior, and 
interface. 


Lisa and the early Macintosh supported only a few implicit connections: containment (disks and folders 
contain folders and documents), sequence, spatial, and document-to-application. The early Mac also 
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supported name-to-object and the newest versions support aliases and warm-links. The various aspects 
of a connection include: 


¢ destination identification of the referenced object 

¢ fan-out can there be more than one destination 

¢ computation the destination may be computed at look up 
¢ kind an optional link type 


Other items that might be associated with links, e.g. direction and behavior, are actually parts of 
explicit connection objects. . 


Interface 
Interface is that part of an object that people and other objects deal with. Each Pink object has a 


concrete visual interface. r representations as well, e.g. audibl ted, 
storage, etc. The various fe include: 


Bbiects are shown 


ters, lines, and pixels. Can 


- ® external visual 


pried: ycimpaired or to get user 
generally i mell, temperature ant 
used for the visually impaired. 
for transmission and storage 

6 rammiatic access and control 


¢ external audible: 
e external other ; 


but tactile might be 


external electr¢ 
external opera 
identificatio 
internal 


eo ¢e¢e0¢e ¢@ 


Operations 


Operations are the computer commands th 
with operations and what they consist of, but’ 
there may be more than one interaction td 
examples.) Interaction is covered in the next s 


We can use 


«English, but I assumé 

languages giver ge of Latin, German, and: 
manipulation also fi rode] since we can describe anything’ we 
actual interaction is qualitatively different. 


A command is directed to the agent that is to perform the action. In the real world this is done by 
naming the agent or by getting the agent's attention and addressing him/her directly. The latter is 
what we do when we select a window. The former depends on a naming scheme which Pink will 
probably address via the ‘forms' mechanism described in the strawman section above. 


The next part is the naming of the action to be performed. Pink uses the old stand-bys of menus, buttons, 
and controls to do this and also provides a textual form that is used in scripts and message boxes (if the 
latter is supported). 


There may be a subject of the action, e.g. the document to be discarded. This is the roll played by the 
selection, if any. 


Finally, one or more phrases may be included that specialize the action to this situation. Direct 
manipulation interactions may allow for the equivalent of a single phrase, e.g. the destination of a 


© Registered /Restricted Human Interface Architecture March lo, 1990 1.3-30 


move. Complex phrase structures, e.g. printing instructions, are represented by dialog boxes. Dialog 
boxes can be tedious, specially when the defaults are correct, so Pink is considering mechanisms that 
support ‘prepackaged’ command-dialog sets. 


Interaction 


Interactions are the way a person and machine communicate. This section deals with the syntax of that 
communication, not the content. The syntax of the content was dealt with in the previous section; the 
symantics of the content are contained in the Taxonomy section below. ; 
People interact with the world, including people, in two distinct ways: symbolically and directly. 
Symbols are representations of something else, and each symbol's meaning must be agreed upon by its 
users. Written and spoken languages are symbolic. Direct interaction deals with way people 
manipulate tangible objects in the physical world, things that we can touch, see, smell, and hear. 


Pink inherits from Lis 
(menu selection and bu: 
AppleScript. 


A very good understa 
around them is essentt 


iteract both symbolica rectly with the world 
interface that is, at best, 
reparation. 


and textually in the form: 
Direct Manipulation 


The most important factor affecting the “¢ 
similarity of manipulations in Pink to ff 
accomplished through the matching of per 
channels they interact.with and the use of sim 
the real world: : 


Caveat: Many: 
and ‘down' butt 
justification for its use:in 


The existence of a contro 


In the real world the hands (plural) and fingers are used: 


to point out objects of interest, 

to grab objects, 

to position and rotate objects in six ways, 

to sense an object's temperature, texture, shape, and size, and 
to apply varying amounts of pressure with different fingers. 


When incorporating direct manipulation into Pink, it is best to maintain a direct correspondence of 
action between the real world and Pink's virtual world. For example, moving something in Pink should 
always be done by the user moving the mouse, rolling a track ball, or other comparable physical 
movement. The limited capabilities of the hardware, e.g the mouse, may make the implementation of 
comparable actions impossible and require the creation of artifacts in order to support a needed 
operation. 
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Design Language 


Elements of the Pink design language should look plausible, as if they could exist in the real world. 
Elements are represented with “cartoons” or caricatures that indicate function through form. On the 
Macintosh and Lisa, buttons had rounded edges and clearly delineated regions and were clicked. Menus 
were square with a shadow and contained more than one item and were pulled down. Icons were 
cartoons with a variety of shapes but one particular size and could be dragged. Icons were not drawn as 
buttons, nor buttons drawn as menus, and so on. 


This applies to the visual behavior of the elements as well; if the element could exist, then it should 
behave as that real world element might behave. If a control in the real world flattens when pressed, 
then the counterpart in the Pink model should also appear to flatten. On the Macintosh, the model for 
controls is based upon highlighting them when the user activates them. 


Elements should not only look plausible, but they should provide clues to the user as to their function. If 
an element is to be int ‘ 
appearance of the elems 
interaction should pra 
indication of a grow 
behavior the elemen 
impression but by its 
significant intervening: 


aré a common 
h the graphic 
yhint at the kind of 
Ot judged by its first 
successful reuse after a 


e this. Indeed, all elemen 
set of visual clues. On th 


ich has a flat 2D physical 
id a consistent 


Bie oe st be visible. On the 
hat delineates the 


model, controls ha 
representation. 
block and have a 


Given the use af animation®: i i isti 1ated 
elements will behave plausibly a i 
represents a transition, like open, than 
the model and only noticed if it did not 
then it should show progress evenly withou 
the user clues as to the kind of operation oc 
a recalculation? Animations of realistic oper: 5: E 
that they are occurring; if an icon is animat r i imation i ite to 
the element. 


Color is used ‘t¢ Oba: : 
redundant clue 'tt licate ee regions and function ; ow element 
may be subtlety distinct fro utton element. The edge an alert element ma ea color, in addition 
to the alert icon, to indicate the kind of alert. The edges of control and the edges of a window will have 
different contrast to indicate that the control is contained within the window. 


Physical Model 


The physical model the Pink look is patterned after is a thin three dimensional block, 1/16” to 1/8” 
thick, that has rolled or extruded edges. The rolled edges are smooth with no abrupt planes. The 
surface of the block is flat. To show content one exposes the interior of the block. To control the block, 
one puts controls on top of the block. This is similar toa TV. One can watch the content which appears 
on the inside of the TV set, or control the content with the dials and knobs on the edges of the TV set 
frame. 


The light source on the block is from the front, approximately centered on the user’s nose. This provides 
for even illumination. Shadows, if any, are transparent. 
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Figure 9. Side view Pink interface objects : 


Taxonomy 


This section describes all of the generic kinds of objects, operations, and interactions. The large: si size of 
this taxonomy is of great.concern.Since-even: inexperienced users will come into contact with my 
It a large number of items : 3 
Other organizations are 


Objects 


“user survey designed to 
re Lisa and/or Macintosh 
nk are explained in more 


This section organizes 
elicit typical organi 
(Blue) and are there 
detail. 


People 


In some situations, : 3 
People objects represent the individ: i : : i Ly or 
through the network. The properties ¢ é : 
picture, preferences for the system and ap 
other machines). Applications should stor 


By default, the system contains at least one 5H é tine, 
each should haye a« : ) t for 
preferences, i 3 ) it 1 ai i a) atterns 


or anything e: 


Person objects are “ess. ists fc ASE S access as 
determined by the content of } 


Environment 


The computer object represents the CPU, all attached peripherals including networks (but not the 
objects on the network), and all system software including the Finder, drivers, cdevs, and inits,(but not 
applications or system utilities). It replaces the Blue system folder and control panel. It provides a 
graphical means and indication of what is in the machine (including memory size and boards), 
configuration information, what is connected to what and mechanisms for holding and activating both 
system software and system level augmentations. The computer object from the start up disk appears on 
the desktop. Computer objects on other disks appear in the disk window; they cannot be placed in 
folders. 


Other environmental objects, e.g. Fonts and Help files, also reside within the computer object. 


Document-based applications could also be included here, maybe. 
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One network object, currently the ‘phone book’, appears on the desktop to represent all attached 
networks and network objects. References to network objects can be dragged from the phonebook to the 
desktop, folders, etc. to provide quick access at later times. The network object cannot be dragged 
onto/into a disk, folder, or other container. 


Each peripheral attached to the machine or network, e.g. disks, scanners, monitors, etc., is represented 
by an object. These objects are normally found within the computer or network objects as appropriate. 
These objects can be opened to set configuration and user preference information. (User preference info is 
actually stored with the current person object.) Peripheral objects can be moved to the desktop, leaving 
a gray place holder behind. The peripherals include: disks, diskette drives, keyboard, mouse, 
monitor(s), scanner, printers, other computers, telephones, etc. 


The desktop is essentially the same as the Mac desktop except that it remembers the placement of all 
objects on it across reboots. 


Data 


e are three 


This groups contains th 3 
each other, and 


main subdivisions, the b 
the marking tools used 


The basic data obje include text (characters, words), graphicsy tmaps, shapes, pixels, 
overlays), and sound(samples, notes). i 


el (time and 
atial (2D, 2 


The structures that 4 
event synchroniza 
1/2D, 3D). 


ata objects include linear 
containers), branck 


The marking tools in 


Tools 


Tools are the behavioral objects that a user ¢G 
system software which the user need not se 
group includes appliances (whole document nt 
scripts. See the Thor's 


ainly serve to relate otherwise dis} 
p links, references, maps), communication (pho 


(warm /hot links). 


Containers 


In this group are the objects that hold data and the objects that hold the data holders. The data 
holders include documents (documents, drawings, images, stacks, spreadsheets, calendars, notebooks, 
scrapbooks, clipboards), annotations, recordings (sounds, animations, video clips, movies, slide shows), 
multi-media (may have several physical pieces), stationery, forms, and simulations (maybe this is just 
an active document). The holder holders include the desktop, folders, trash can, mailbox, disks (double 


grouped?) 
Interaction Controls 


This last group contains all the objects used for (in)direct manipulation of Pink's virtual reality. They 
are all artifacts, i.e. objects that generally do not exist in the real world but which are required by the 
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computer to overcome hardware limitations. Ideally they would exist only in places where comparable | 
real world objects exist or where Pink has extended the real world metaphor. Included are windows 
(windows, dialogs, alerts, utility windows, subwindows, window sets, progress indicators), menus (menu 
bar, pull-down, pop-up, tear-off, menu title), buttons (single action, continuous action, check box, radio, 
command keys, cursor keys), window parts (scrollbars, grow box, zoom box, close box, window splitters), 
virtual track ball, etc. 


Operations 


Regardless of the actual tasks a person performs, all actions can be classified into one of the following 
categories: 


¢ Observe gather information through the five senses 

¢ Navigate ascertain current location, navigate in real and symbolic space (of self) 
¢ Ideate subconscious generation of ideas, alternatives 

¢ Decide 

¢ Select 

¢ Manipulate 

e 


Communicate s 


ey don't seem to be 


These categories ar 


Observe op, restart, 
Navigate 
Ideate 
Decide » 
Select select one, many 
Manipulate create, destroy, initi 
repair, verify, size, 
disconnect, ungroup, ur 
Communicate send, get, connect to, disc 


paste, replac 


‘otate, flip, € 
evert, save ve} 


Interactior 


Regardless o 
to-machine sid 


Direct 
Symbolic click-on command, type-in command, dialog, spoken command 
Feedback static display, animation, sound, visual change, completed list 
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Architecture 


The Pink Run Time system will provide Pink with these capabilities 


* Shared Libraries of code, providing for small applications, and for 
updating the system without breaking applications. 


e A storage allocator. 
¢ Semaphores, for use in synchronizing multi-threaded applications. 
° Exception handling, provided in conjunction with the C++ language. 


e Libraries of classes that may be dynamically accessed during program 


Complete document Now. 


rn a 
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Utility Classes 


Arnold Schaeffer x8117 


I hate data structures. You probably do too? 
dealing with the most common data structu 


ancements to 


classes. 
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Introduction 


I hate data structures. You probably do too. Fortunately for you, Pink provides a set of classes for 
dealing with the most common data structures you are likely to need. Use these classes whenever 
you can because your code will get faster as we make performance enhancements to these “utility” 
classes. 


The Utility Classes are roughly divided into two sections: the Collection classes and the CS101 
classes. The Collection classes provide a set of classes somewhat equivalent to the collection classes 
found in Smalltalk. These classes include sets, bags, dictionaries, stacks, deques, queues, priority 
queues, dynamic Arrays, sorted sequences and run arrays. The Collection classes are implemented 
using the CS101 classes which are “raw” data structure classes like hash tables, linked lists, heaps, 
trees, etc. Most users of the Utility Classes should only use the Collection classes. The choice of 
which collection class to use allows you to specify the kind of operations you expect to do on a data 
set as well as some hints as to the ex ected size of the data set. The computer can then choose.the 
proper CS101 class to use: 


Architectural Ove) 


The Utility Classes are asically a set of classes for managing and} 
particular utility clas t you use will be determined by the ki 
to perform on the data: For the pu of this architectural 6 
classes you will be classes. Other cla 
used only as imple 


ng data. The 

ions that you would like 
assumed that the utility 
ty classes are 


All of the collectio 
baseclasses add protocol for spec iahz 
provides methods for adding elemen 
querying whether an object is an element 
removing all the elements from a collection 
another collection; destroying (and removin 
enumerating over the elements of a collecti 


Deciding what sllect ee oe 


collection that h $3 
all maintain the order of the elements put into ther: Stacks have a policy hat the last element 
added to it is the first element removed. Queues have a policy that the first slement added is the 
first element removed. Stacks and queues are good choices when the data you are managing follows 
one of these policies. Deques are ordered (like stacks and queues) but there is no implicit element 
removing policy; therefore, elements can be added at any place in the deque and removed in any 
order. Deques, stacks and queues are all ordered by some external (to the elements) procedure. The 
individual elements in these collections have no internal notion of order. Operations on stacks, 
queues, and deques that involve adding/removing from the beginning or the end are all O(1). 
Operations on stacks, queues, or deques for arbitrary removing/querying are all O(N). 


If the elements of the collection have an external notion of ordering based on an index then there are 
two collections available for use. Dynamic Arrays allow elements to be associated with an index. 
Adding/Retrieving elements to/from the collection at a specific index is O(1). Growing the array is 
very expensive. Run Arrays allow elements to be associated with an index. Run Arrays are very 
efficient when there are long runs of the same elements at contiguous index values. All operations 
on run arrays are O(logN). 
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If the elements have an internal notion of ordering then there are two choices of collections that you 
can use. Priority Queues provide a collection where the elements are only partially ordered based on 
some internal notion of ordering. For example, many applications require that elements are 
processed in some order; however, not necessarily all at once or in fully sorted order. Examples of 
this kind of collection could be found in an event scheduling system where the most urgent element 
is always scheduled first. SortedSequences provide a collection where the elements are fully ordered 
based on some internal notion of ordering. Of course, operations on sorted sequences are more 
expensive than operations on a priority queue. This is because there is some overhead to pay for 
maintaining the sorted sequence. Operations on priority queues are all O(logN). Operations on 
Sorted Sequences are also O(logN); however, there is significant overhead in the balancing 
mechanism. Sorted Sequences are optimized for access speed at the expense of update speed (i.e. it 
is assumed that access happens more frequently than add or remove). 


Unordered collections have no notion of ordering. Iterating through an unordered con ecnon returns 
the elements of the collectian% J operations on unordered collecti . 

Unordered collections in aries. Sets are a collection.¢: 
support the additional pj n, xor, and difference. Di 
arrays) associate an el 'y with an element desig 
to a dictionary involves r to thedictionary 
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eS s (associative 
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Generic Objects 


The class MCollectible defines the generic object class from which all other classes are derived. It 
is an abstract class in that many subclasses will redefine some or all of the methods presented below. 
MOrderableCollectible should be mixed into objects which might have to be ordered. If you wish 
to use the utility classes, your objects should descend from one of these classes. 


MCollectible 


M@QrderableCollectible 


MCollectible 


asses are derived. Itis 
thods presented below. 
ds are described in the 


The class MCollectible defines the generic object class from which 
an abstract class in th many Sune laaee will redefine some or. 
There are also metha 3 


MCollect ii 
in their declaratio 


in their definition file (.c). e 


class MCollectible { 
public: 
MCollectible(); 
virtual Beit eich 
virtual 
virtual 
virtual 
virtual MCc¢ 
inline boolean 


Ast MCollectiblé 
' const; 
perator== =(const MOrderableCo 


inline boolean operator!=(const MOrderableCollectibles rol @ ai ar 
} 


typedef boolean (MCollectible::* MCollectibleCompareFn) (const MCollectible*) ; 
typedef long (MCollectible::* MCollect ibleHashFn) (); 


boolean MCollectible::IsSame(const MCollectible* obj) 
The default function is a pointer comparison. 


long MCollectible: :Hash() 
Returns a value suitable for use as a hashing probe for this. The default function will simply return 
the address of the object. The default function is almost certainly not adequate if you are overriding 


IsEqual because you need to make sure that all objects that “are equal” to each other return the 


1. Bold type is used for methods which almost always should be overridden. 
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same hash value. For example, a TText object would return a hash value computed using the 
characters in the string instead of the address of the string. 


boolean MCollectible: :IsEqual (const MCollectible* obj) 

Returns TRUE if obj is isomorphic to this. The default function will throw you into OpusBug and 
give you a nasty message. For example, the IsEqual method for TText objects will do a string 
comparison. All of the utility classes allow you to specify what method to use when comparing 
objects for insertion, deletion, etc. 


MCollectible* MCollectible::Clone() const 7 
This method is declared and defined automatically when using the MCollectibleDeclarationsMacro. 
It is always defined as { return new subclassName(*this); }. This provides a general 
polymorphic duplication function. 


MOrderableCollec 


MOrderableCollect 


biects which might wai 
which are passed to TP : 


‘ordered. Objects 


virtual boaiean: 
virtual boolean 
inline boolean operator<‘ 
inline boolean operator>(cén 
inline boolean operator>=(cor 
inline boolean operator<=(con 


typedef book 


boolean MCollec pi Than (const MOrderableCoz 
Returns TRUE if obj is “greater an” this. The default function will throw you into OpusBug and 


give you anasty message. For example, the IsGreaterThan method for TText objects will do a 
string comparison. 


boolean MCollectible: :IsLessThan(const MOrderableCollectible* obj) 
_ Returns TRUE if obj is “less than” this. The default function will throw you into OpusBug and give 


you a nasty message. For example, the IsLessThan method for TText objects will do a string 
comparison. 
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Collection Classes 


Collection classes are used to group objects in meaningful ways. The system provides 
implementations of many of the collection classes from Smalltalk. Use these classes. They will get 
faster, smaller, taste better, and less filling. 


TCollection 


TCollection 


A TCollection represents a group of object 
collection classes inherit methods. There ar 
Collections all provide a facility for iterating 
in the section on.j 


class TColl 
public: 


TCollection (MCo bleCompareFn testfn) ; 
virtual ~TCollection(); 


virtual void Add (MCollectible* obj); 

virtual void Add(TCollection* collection); 

virtual MCollectible* Remove (const MCollectible&é obj); 
virtual void RemoveAll (); 

virtual void DeleteAll(); 

virtual long Count () const; 

virtual MCollectible* Member (const MCollectible& obj) const; 
virtual TIterator* CreateIterator() const; 


} 


TCollection (MCollectibleCompareFn testfn) 
Create anew TCollection. All future operations will use test fn for a comparison when needed. 
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virtual ~TCollection() 
Destroy the mother. 


void TCollection: :Add(MCollectible* obj) 
Add obj to this. 


void TCollection: :Add(TCollection* collection) 
Add all of the objects in collection to this. Essentially equivalent to getting an iterator for the 
collection passed in and adding each element in the collection to this. 


MCollectible* TCollection: :Remove (const MCollectible&é obj) 

Remove obj from this. Return the object which was actually removed (which if you are using an 
IsEqual test function may not be the same as the object passed in only “equal.”) 

void TCollection: :Rem Alt 
Remove all of the objects# 


void TCollection: 
Remove all of the objec 
(that is, the destructor 


ight have owned 


ction is called for each object j in the colle 


long TCollection: 
Return the number @ 


MCollectible* @ . — 
Each object in thi i : j estFn 
returned true. Ré 


TIterator* TCollection: :Create 
This method returns a new iterator which: 
collection. See the special section on itera 


over the obj 


TBag 


The TBag class‘3 
which objects can‘ap} 
the Hash() method and the ft 


hould override 


const long kInitialBagSize; 


class TBag: public TCollection { 
public: 
TBag (MCollectibleCompareFn testFn = &MCollectible::IsSame, 
long bagSizeGuess=kInitialBagSize) ; 


virtual ~TBag(); 
virtual void AddWithOccurrences (MCollectible* obj, long number) ; 
virtual long OccurrencesOf (const MCollectible* obj) const; 


virtual MCollectibleHashFn GetHashFunction (MCollectibleHashFn) const; 


2. If you are using an IsEqual TBag, only the first object added that “is equal” to other objects 
_ added is retained by the collection and returned as the result of calls to member, remove, etc. 
This can make memory management awkward. Think about this when using an “is equal” bag. 
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virtual void SetHashFunction (MCollectibleHashFn) ; 
} 


TBag::TBag(MCollectibleCompareFn testFn, long bagSizeGuess) ; 
Create a bag which can hold at least bagSizeGuess elements. BagSizeGuess.is used to determine 


what implementation class to use for bag. 


void TBag: :AddWithOccurrences (MCollectible* obj, long number); 
Add obj to this with number of occurences number. 


long TBag::OccurrencesOf (const MCollectible* obj) const; 
Return the number of occurences of obj in this. Zero indicates that obj is not in the bag. 


MCollectibleHashFn TBag::GetHashFunction() const 
Return the hash function hej hash.tab 


void TBag::SetHashF 
Set which member func S 
&MCollectible: :Ha AY OVEETT i AS ting to the hash 
table). You can use an : Signature of 

and returning a long). 


The TSet class is a subcla ee 
which objects can appear only once. Obj 
Hash() method and the IsSame() or 


const long kIinitialSetSize; 


class TSet: 


public: 

TSet (MC ‘ 
lon alSetSize); 

virtual ~TSet (); 
virtual void Difference(const TSet& setl); 
virtual void Difference (const TSet& setl, TSet& result); 
virtual void Intersection(const TSeté& setl); 
virtual void Intersection(const TSet& setl, TSet& result); 
virtual void Union(const TSet& setl); 
virtual void Union(const TSeté& setl, TSet& result); 
virtual void Xor(const TSet& setl); 
virtual void Xor(const TSet& setl, TSet& result); 
virtual MCollectibleHashFn GetHashFunction (MCollectibleHashFn) const; 
virtual void SetHashFunction (MCollectibleHashFn) ; 


} 


TSet::TSet (MCollectibleCompareFn testFn, long setSizeGuess) ; 
Create a set which can hold at least setSizeGuess elements. SetSizeGuess is used to determine what 
implementation class to use for set. 
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void TSet::Difference(const TSet& setl);: 
Destructively modify this to contain a set of elements of this that do not appear in set. 


void TSet::Difference(const TSet& setl, TSet& result); 
After this function is called, result will contain a set of elements of this that do not appear in 
setl. 


void TSet::Intersection(const TSet& setl); 

Destructively modify this to contain everything that is an element of set1 and this. 

void TSet::Intersection(const TSet& setl, TSet& result); 

After this function is called, result will contain everything that is an element of set1 and this. 


void TSet::Union(const TSet& setl); 


& result); 


erything that is an el etl or this. 


void TSet::Xor(c 
Destructively modify 
both. 


setl or this, but not 


void TSet: :Xor( 
After this function: 
this, but not bot 


MCollectibleHashFn TSet: :Get 
Return the hash function being used b 


void TSet::SetHashFunction (MCollec 
Set which member function to call as a hash 
&MCollectibl 
table). You can 


ethod taking no fp; 


TDictionary 


The class TDictionary is a subclass of TCollection. It represents a collection of paired objects 
(associations). Because dictionaries are sometimes used to represent a bijective mapping, functions 
for retrieving a key given a value are provided along with the usual access functions (however, this 
will probably be slow). Objects which are inserted into the TDictionary should override the 
Hash() method and the IsSame() or IsEqual() method. These are used internally by the 
TDictionary class. Note: Iterators on the TDictionary class return objects of class TAssoc. 


const long kInitialDictionarySize; 
class TDictionary: public TCollection { 


public: 
TDictionary (MCollectibleCompareFn testFn = &MCollectible::IsEqual, 
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long dictionarySizeGuess=kInitialDictionarySize) ; 
virtual ~TDictionary(); 


virtual MCollectible* ValueAt (const MCollectible& key) const; 
virtual const MCollectible* KeyAt (const MCollectible& val) const; 
virtual MCollectible* Remove (const MCollectibleé key); 

virtual MCollectible* DeleteKey (MCollectible* key); 

virtual void DeleteAllKeys(); 

virtual void DeleteAllValues (); 

virtual void AddKeyValuePair(const MCollectible* key, 


MCollectible* val, 

boolean replace = TRUE); 
virtual MCollectibleHashFn GetHashFunction(MCollectibleHashFn) const; 
virtual void SetHashFunction (MCollectibleHashFn) ; 


TDictionary: :TDictio: jpareFn testFn, 


rysizeGuess elements. SizeGuess is 


se for the dictionary. 


Create a dictionary whic 
used to determine what: 


MCollectible* TDi¢é 


onary: :ValueAt (const MCollectibz const 
Return the value ass 


d with the key. Return NIL if the ke 


KeyAt (const MC¢ 


MCollectible* TB: r : 
Remove the key, value pair Ya of 
this call. 


MCollectible* TDictionary: :Delete 
Delete the key from the key, value pair assoc 
dictionary. Return the value that was remov 


If replace=FALSE ‘ ilue pair to the table if pier. i ng key,value pair. 
Otherwise, if replace=TRUE the key, value pair to the hash table. Either way, return the key 
that existed (if any) in the hash table before this call. Proper memory management may involve 
checking to see if the key returned is “the same” as the key passed in when replacing key, value 
pairs. 


a 


Y 


void TDictionary: :DeleteAllKeys () 
Remove all of the entries in the dictionary. Reset the count to be zero. Call the destructor on every 
key in the dictionary. 


void TDictionary: :DeleteAllValues () 

Remove all of the entries in the dictionary. Reset the count to be zero. Call the destructor on every 

value in the hash table. If you have a value which appears more than once, you will be sorry you 

used this method because the utility classes will delete the same object more than once. This is not 
good. 
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MCollectibleHashFn TDictionary::GetHashFunction() const 
Return the hash function being used by the hash table. 


void TDictionary: :SetHashFunction (MCollectibleHashFn) 

Set which member function (of the objects in the dictionary) to call asa hash function. By default, 
this is set to &MCollect ible: :Hash (which is usually overridden in the objects you are adding to 
the hash table). You can use any hash function that you like as long as it has the type signature of 
MCollectibleHashFn (which is basically a method taking no parameters and returning a long). 
Most of the time, you won’t need to do this. 


TPriorityQueue 


A TPriorityQueue is a subclass of TCollection which Feeus the elements of the collection 
partially ordered based on.some.ordering function. 
collect a set of records, t 

There is considerable de 
TCollection since it r 
the way in. Objects w. 
IsLessThan() and 
class. Note: Iteratars on a TPriorityQueue elas do NOT cts: ‘in order.” 
Because a TPriori i a very expensive 
operation in gener jlied by the utility 
classes but not a: S 


class TPriorityQueu 
public: 
TPriorityQueue (MOrderableCo#3 
&MOrderableCé 
virtual ~TPriorityQueue() ; 
virtual void 
virtual MQ 
virtual } 
virtual 
virtual 
virtual voz 


} 


it'yComparisonFunction (MCO 


TPriorityQueue: :TPriorityQueue (MOrderableCollectibleCompareFn testFn) ; 

Create a new priority queue. Use test Fn to determine whether larger objects are removed first or 
last. A test of IsLessThan means that larger objects are removed first and smaller objects are 
removed last. A test of IsGreaterThan reverses this. 


void TPriorityQueue: : Insert (MOrderableCollectible* obj); 
Insert obj in this and return it as a result. 


MOrderableCollectible* TPriorityQueue: :Pop(); 
Remove the object with the “highest” priority from the priority queue and return it. 


MOrderableCollectible* TPriorityQueue: :Peek() const; 
Return the object with the “highest” priority from the priority queue but don’t remove it. 
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MOrderableCollectible* TPriorityQueue: :Replace (MOrderableCollectible* obj); 
Roughly equivalent to inserting the obj into the priority queue and then removing the object with the 
highest prioriy. 


MCollectibleCompareFn TPriorityQueue: :GetEqualityComparisonFunction() const 
Return the equality comparison function being used by the priority queue. 


void TPriorityQueue: :SetEqualityComparisonFunction (MCollectibleComparefF'n) 

Set which member function to call as the equality comparison function when removing objects from 
the queue, checking to see whether a given object is a member, etc. This defaults to IsEqual. Most 
of the time you won’t want to change this. 


TSequence 


A TSequence is an abstra is whose elements are ordered 


class TSequence: pt 


public: : 
virtual After(const MCollec: 1) *COnses 
virtual Before (const MCol Ob)" const; 


virtual MCol 
virtual MCol 
virtual voi 
virtual loa i anst; 
virtual voi 
virtual TSequencelterat 


const 
inthis or: 


MCollectible* TSequence: :After (cons 
Return the object found after obj in this or 


MCollectible 
Return the first object 


MCollectible* TSequence::Last() const 
Return the last object in this. 


void TSequence: :Concatenate (TSequence* aCollection) 
Concatenate aCollection onto the end of this. 


long TSequence: :OccurrencesOf (const MCollectible& obj) const 
Return the number of times obj is in this. 


void TSequence: :Reverse() 


this is destructively turned into a collection which contains the same elements as this, but with 
the order of the elements reversed. 
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TSequenceIterator* TCollection: :SequenceIterator() const 

This method returns a new sequence iterator which is suitable for use in iterating over the objects in 
the collection. Sequence iterators differ from normal iterators in that they can start at the last object 
or the first object and go in either direction. See the special section on iterators on page 35. 


TDeque 


A TDeque is a subclass of TSequence which is ordered based on the order elements are added to or 
removed from the collection. Objects which are inserted into the TDeque should override the ~ 
IsSame() or IsEqual() method. 


class TDeque: public TSequence { 
public: 
TDeque (MCollectibleCompareFn:-te 
virtual ~TDeque 
virtual 
virtual 
virtual 
virtual 
virtual 


SEE: 


5 Gi Re 


&MCollectible::IsSame) ; 


-ectible* obj); 
-lectible* obj); 


RemoveFirst(); 
AddAfter(const MCollecti 
MCollectible* . 
»fore(const MCollé 


virtual void 


TDeque: : TDeque (MCGEPES 
Create a new TDeque. 


MCollectible* TDeque: :RemoveLast't 
Remove the last object in this and return it 


MCollectible* 


k -nDeque: :RemoveFirst 
Remove the firs} ot. 


1 this and return 


void TDeque: :AddBefore (const MCollectibles exist, MCollectible* new) 
Add the new object before exist in the collection. 


void TDeque: :AddLast (MCollectible* ob}) 
Add ob3 as the last object in the collection. 


void TDeque: :AddFirst (MCollectible* obj) 
Add obj as the first object in the collection. 


TStack 

A TStack is subclass of TSequence in which the last item added to the stack is the first item taken 
out of the stack (LIFO). Objects which are inserted into the TStack should override the IsSame () 
or IsEqual() method. The iterator for a stack will return objects in the order they would be 


@ Registered /Restricted Utility Classes Thursday, March 1, 1990 DA2< 412 


returned if repeated Pops were issued to the stack. 


class TStack: public TSequence { 
public: 
TStack (MCollectibleCompareFn testFn = &MCollectible::IsSame) ; 
virtual ~TStack(); 
virtual MCollectible* Pop(); 
virtual void Push (MCollectible* obj); 
} 


TStack::TStack (MCollectibleCompareFn testFn) 
Create a new stack. 


void TStack::Push(MCollectible* obj); 
Add the object to the top of 


MCollectible* TStack 


Remove the object on th it. Return NIL if nothi 


TQueue 


A TQueue is a subcl 
taken out of the que 
IsSame() or IsEq ! 
would be returned to the stac 


which the first item ai 


gueue is the first item 
sich are inserted in! 


class TQueve: public TSequence: 
public: : 
TQueue (MCollectibleCompareFn te 
virtual ~TQueue(); : 
virtual void Insert (MC tible* 
virtual MC 


TQueue: :TQu lec z Fn testFn); 
Create a new quetie 


void TQueue::Insert (MCollectible* obj); 
Add an object to the queue. 


MCollectible* TQueue: :Pop(); 
Remove the oldest object in the queue (First Jn, First Out). Return NIL if nothing is in the queue. 


TSortedSequence 


A TSortedSequence is a subclass of TSequence in which all of the objects in the collection always 
remain sorted. New objects will be inserted in sorted order. All objects in the sequence must be 
MOrderableCollectibles. There is considerable debate at this point as to whether this class 
really should be a subclass of TSequence since it relies on the good nature of the user to supply 
MOrderableCollectibles on the way in. Objects which are inserted into the TSortedSequence 
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should override the IsEqual(), IsLessThan() and IsGreaterThan() methods. 


class TSortedSequence: public TSequence { 
public: 
TSortedSequence (MOrderableCompareFn testFn = &MCollectible::IsLessThan) ; 
virtual ~TSortedSequence() ; 


} 


TSortedSequence: :TSortedSequence (MOrderableCompareFn testFn) ; 
Create a new sorted sequence. 


TIndexedSequence 


A TindexedSequence is 
be randomly accessed via 


class TIndexedSequ: 


public: 
virtual 
virtual 
virtual 
virtual 
virtual 
virtual 


LowBound() const; 
os ound() const; 


virtual MCollectible* At, 
virtual void Rep 


virtual boolean 


:©Fill(MCollectible*. 
:Ob5. This does not duplicate the objét 


Fill this with element: pointer to the object. 


t; 


long TIndexedSequence: :LowBound() ; 
Return the index of the lowest bound in this collection. 


long TiIndexedSequence: :HighBound(); 
Return the index of the highest bound in this collection. 


MCollectible* TIndexedSequence::At (long index) const; 
Return the object in this at the index. If index is past the end of this then FAIL. 


MCollectible* TIndexedSequence: :AtPut (long index, MCollectible* obj); 
Add the obj to this at the index. The object that was previously at this index is returned from 


AtPut. If index is past the end of the collection then FAIL and do not add this object to the 
collection. 
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boolean TindexedSequence: :Find(const MCollectible* obj, long& findresult, 

long start=0, long end=0); 
If there is an object in this which IsSame or IsEqual (depending on the test function for the indexed 
sequence) to obj then return TRUE and set findresult equal to the index of the object. Otherwise 
return FALSE. If start or end is specified (as longs), these are used to determine where in the 
collection to start and end searching. 


MCollectible* TIndexedSequence: :AtInsert (long index, MCollectible* obj); 
Insert the obj into the TIndexedSequence at the specified index. Effectively, the indexed sequence 
is grown one object. If index is out of the bounds of the TIndexedSequence then FAIL. 


void TIndexedSequence: :Replace (TIndexedSequence* seq, TIndexedSequence* rep, 
long seqstart=0, long thisstart=0, 

ee ee SON : 

Sin rep. Use seqstart, thisstart; tart to 

ch string to start from. 


Replace elements in this m 


earchresult, 


QO); 

llection then the result 
f the first object in the 
Seqstart and thisstart 


subcollection in seare: 
can be used to contr@: 


TArray 


An TArray is an abstract subclass of TIn 
elements of the sequence via a numerical 
constant access and update time. Objects w 
IsSame() or IsEqual() method. These ar 


class TArray: 
public. 
TArray (MCO 


ndexedSequ 


‘estFn = 


lon q long offset=0); 
virtual ~TArray(); 
virtual void Grow(long howmuch, long extraspace = 0, 
Boolean addToTop = TRUE); 
virtual void Compress(long from, long howmuch) ; 
virtual MCollectible* Append (MCollectible* obj); 
virtual void GrowTo (long maxIndex) ; 
virtual void SetAutoGrowFlag (Boolean autoGrow = TRUE); 
virtual Boolean GetAutoGrowFlag() const; 


} 


TArray::TArray (MCollectibleCompareFn testFn, 

long initialSize, long offset=0) 
Create a new array of size initialSize and fill it initially with NIL. The offset of the first element 
of the array is offset. 
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void TArray::Grow(long howmuch, long extraspace, Boolean addToTop) 

Grow the indexed sequence by howmuch. The additional elements can be inserted at the top of the 
array or the bottom depending on the value of the addToTop flag. extraspace is the amount of 
extraspace to use as a slush fund for future At Insert operations to avoid copying the whole array. 


void TArray::GrowTo(long index) 
Grow the array in whatever direction is necessary to make index a valid index into the array. 


void TArray::Compress(long from, long howmany) : 
Compress (remove) entries from the array beginning at entry from and continuing for howmany 
entries. 


MCollectible* TArray: sAppene (NCoTTectthle* obj) 
Shorthand for At Insert (HighBound.. E a 


void TArray: :SetAut 
Set the autoGrowFlag; 
out of bounds, automa 
inserts and puts. Retu 


tLoGrow = TRUE) 
then instead of FAILi 


an array index is 
, only grow on 
virtual” grow). 


Boolean TArray 
Return the AutoGro 


TRunArray 


A TRunArray is a subclass of TIindexe: 
that tends to be sparse over long runs. 


class TRunArray: public TIndexedSequence { 
public: 
TRunArray (MCollectibleCompareFn testFn = &MCollectible::IsSame, 
long size=1, long offset =0); 
virtual ~TRunArray(); 
virtual void AtCountPurge(long index, long count); 
virtual MCollectible* AtCountReplace (long index, long count, 
MCollectible* obj); 
virtual MCollectible* AtCountInsert (long index, long count, 
MCollectible* objt); 


TRunArray: :TRunArray (MCollectibleCompareFn testFn, 
long size, long offset = 0); 
Create a new run array of size = 1 with offset zero for the first element. 
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MCollectible* TRunArray::AtCountInsert (long index, long count, MCollectible* 
ob )% 

Insert a run of obj, count objects long into the run array at the specified index. Effectively, the array 
is grown by count objects. If index is out of the bounds of the array then return NIL. 


void TRunArray: :AtCountPurge (long index, long count); 
Remove the objects in the run array starting at index and continuing until index+count-1. If either 
the upper or lower bounds of the element to be removed set is out of the array bounds then return 
NIL and do not perform the deletion. : 
MCollectible* TRunArray: :AtCountReplace (long index, long count, MCollectible* 
obj); | 
Loosely equivalent to a call to PurgeAt to remove objects in the run array followed by an InsertAt 
he replacement range is out of boun 


Otherwise return obj. 
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Simple Classes 


These simple classes are used in the implementation of many CS101 classes. 


MCollectible 


MOrderableCollectible TDoubleLink 


TAssoc 


‘ome other 
s implementing 


y, these structures are 0 
ully not returned to the.; 


A TAssoc is used to hol 
higher level object (e.g. # 
their own classes migh 


class TAssoc 
public: 
TAssoc(); 
TAssoc (MCo 
virtual 


TLink 


A TLink is primarily us lementation of linked lists. Typ: ctures are 
owned by some other higher level object (e.g. a dictionary) and are usuall rned to the user. 
Users implementing their own classes might wish to use TLinks in their implementations. 


class TLink ({ 


public: 
TLink(); 
TLink(TLink* link = NIL, MCollectible* obj = NIL); 
virtual ~TLink (); 
virtual void SetNext (TLink* link) ; 
virtual TLink* GetNext (); 
virtual void SetValue (MCollectible* obj); 


virtual MCollectible* GetValue(); 


@ Registered /Restricted Utility Classes Thursday, March 1, 1990 2.1.2 - 18 


TDoubleLink 


A TDoubleLink is primarily used in the implementation of doubly linked lists. Typically, these 
structures are owned by some other higher level object (e.g. a dictionary) and are usually not 
returned to the user. Users implementing their own classes might wish to use TDoubleLinks in 
their implementations. 


class TDoubleLink : public TLink { 
public: 
TDoubleLink(); 


TDoubleLink (TLink* link = NIL, MCollectible* obj = NIL); 
virtual ~TDoubleLink () ; 
virtual void SetPrevious (TLink* link); 


virtual TDoubleLink* GetPrevious(); 


TEdge 


‘between the user and 
, it is not part of the 


F to communicate information about edge 
ught of as a copy of some aspect of a grag 
wn their representations. < 


A TEdge is an object 
the system. It can be 
graph itself because gr 


class TEdge 
public: 

TEdge(); 
virtual ~TEdge ( 
TEdge (TVertex* from, TVert 
TVertex* GetFrom(); 
TVertex* GetTo(); 
WeightType GetWeight (); 
void Sere Ponti Verres: Vv 
void 
void 
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CS101 Classes 


CS101 classes are classes which implement classic computer science data structures. Theseinclude . 
hash tables, linked lists, trees, graphs, etc. In general, you shouldn’t use these classes directly - they 
are used as implementations for the collection classes. The collection classes isolate you from a 
particular implementation used for a collection (which will be a CS101 class). For example, a set 
could be implemented as a linked list, a c-array or a hash table depending on the operations 
performed, number of elements, etc. Eventually, the collection classes will be smart about making 
these choices for you automatically based on a specification from the user (the size hint is a start in 
that direction). 


TLinkedList 


TDoubleLinkedL TBinaryTree 


THashTable 


The class THashTable is a subclass of MOL 
another MCollee¢: 


using an IsEqual 


(see page 35) on THashTables setae TAssoc objects. You can use the Get Key ( ) and GetValue () 
call on the TAssoc to get what you want. 


const long kDefaultHashTableSize; 
const long kDefaultGrowthRate; 
const long kDefaultRehashThreshold; 


class THashTable: public MCollectible { 
public: 
THashTable( MCollectibleCompareFn testFn = &MCollectible::IsSame, 
long tablesize=kDefaultHashTableSize, 
long growthrate=kDefaultGrowthRate, 
long threshold=kDefaultRehashThresholda) ; 
virtual ~THashTable(); 
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virtual long Count () const; 


virtual MCollectible* Remove (const MCollectible& key); 

virtual MCollectible* Delete (MCollectible* key); 

virtual MCollectible* Member (const MCollectible& key) const; 

virtual void DeleteAll(); 

virtual void DeleteAllKeys(); 

virtual void DeleteAllValues({); 

virtual void RemoveAll (); 

virtual void Grow(); 

virtual MCollectible* Add(const MCollectible* key, . 
. MCollectible* value, boolean replace=TRUE) ; 

virtual MCollectible* Retrieve (const MCollectible* key); 

virtual long GetGrowthRate() const; 

virtual long GetRehashThreshold() const; 


virtual void 
virtual void 
virtual MCollecti 
virtual void 


} 


Rate (long rate); 
threshold(long threshold). : 
ction (MCollectibleHas: sonst; 
ction (MCollectible 


ble (MCollectibleCompareFn testF 
long tablesize, long growth 
4n:initial tablesize, growthrate | 


THashTable::THas 


g threshold) 
Return the new 


tch...Threshold is a 


Create a new hash 
hashtable. TestFn 
number from 0 to 180 


long THashTable: :Count () 
Return the number of entries in the hast 
RemoveAll, DeleteAllKeys or DeleteA 


MCollectible* THashTable: 


surrogate key. In cases'such as this, use the Delete method if you want the hash table to delete the 
actual key before returning the value. You could also call the Member method to retrieve the actual 
key in the dictionary before removing it. 


MCollectible* THashTable: :Delete (MCollectible* key) 

Delete any entry for the key in the hash table and removes the value from the hash table. Return 
the value removed if there was actually an entry to remove or NIL otherwise. If the key used as a 
parameter is the same as the key in the hashtable, it is still deleted. Any operations on this deleted 
object will cause the usual storage management problems. 


MCollectible* THashTable::Member(const MCollectibleé& key) const 
Each object in this is compared to key using the function testFn. Return the object which was found 
which IsEqual or IsSame to the object passed as a parameter. Return NIL if no object was found. 


void THashTable: :RemoveAll () 
Remove all of the entries in the hash table. Reset the count to be zero. If you don’t have pointers to 
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all of the key, value pairs stored elsewhere in your program, you have a memory leak. You can use 
DeleteAll, DeleteAllkeys or DeleteAllvalues if you would like the utility classes to destroy 
the objects in the hashtable. 


void THashTable: :DeleteAll () ‘ 

Remove all of the entries in the hash table. Reset the count to be zero. Call the destructor on every 
key and every value in the hash table. If you have a key which also appears as a value or a value 
which appears more than once, you will be sorry you used this method because the utility classes will 
delete the same object more than once. This is not good. 

void THashTable: :DeleteAllKeys () 

Remove all of the entries in the hash table. Reset the count to be zero. Call the destructor on every 
key in the hash table. 


void THashTable: :DeleteAllvVal 
Remove all of the entries 
value in the hash table 
used this method becau 
good. 


the count to be zero. Call the dest 
appears more than once, yor 
lete the same object me¥ 


‘ow () 
ow by the rehashsize. 


void THashTable: 
Force the hash table: 
MCollectible* f st MCollectib!] 
#place=TRUE) 


If replace=FALSE 
Otherwise, if replace=TR 
that existed (if any) in the hash 
checking to see if the key returned 
pairs. 


long THashTable: :GetGrowthRate() c 
Return the growth rate for the hash table. 


const 


ble. Threshold is a 


void THashTablée=:5 ‘owthRate (long rate) 
Set the growth rate for the hash table. 


void THashTable: :SetRehashThreshold (long threshold) 
Set the rehash threshold for the hash table. 


MCollectibleHashFn THashTable: :GetHashFunction() const 
Return the hash function being used by the hash table. 


void THashTable: :SetHashFunction (MCollectibleHashFn) 3 

Set which member function to call as a hash function. By default, this is set to 

&MCollectible: :Hash (which is usually overridden in the objects you are adding to the hash 
table). You can use any hash function that you like as long as it has the type signature of 
MCollectibleHashFn (which is basically a method taking no parameters and returning a long). 
ere ee 


3. D11 may not allow you to set the hash function after there are objects in the hash table. This 
bug will be fixed shortly by rehashing the table immediately after a SetHashFunction call. 
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Most of the time, you won’t need to do this. 


TLinkedList 


A linked list object is useful for storing lists of MCollectibles. Linked lists are particularly useful 
when storage requirements are unpredictable and extensive manipulation of the structure 

(insertions, deletions) is required. Objects which are inserted into the linked list should override the 
IsSame() or IsEqual() method depending on what test function is passed into the constructor. 


. 


class TLinkedList: public MCollectible { 
public: 
TLinkedList (MCollectibleCompareFn testFn = &MCollectible: 


:IsSame) ; 


} 


virtual 
virtual 
virtual 


virtual 
virtual 
virtual 
virtual 
virtual 
virtual 
virtual 


virtual 


virtual 
virtual 
virtual 
virtual 
virtual 
virtual 
virtual 


protected: 


~TLinkedList (); 


MCollectible& obj, 


RemoveAll (); 
RemoveFirst (); 
RemoveLast (); 
ler 


void 
void 
MCollectible* 
MCollectible* 
MCollectible* 
ctible* 


Tet oes 


SetFirst (TLink*) ; 
SetLast (TLink*); 


virtual TLink* MakeNewLink (TLink* n = NIL, 
MCollectible* v = NIL) const; 

virtual TLink* FirstLink(); 

virtual TLink* LastLink (); 

virtual TLink* Remove (TLink* 1); 

virtual TLink* RemoveAfter(TLink* 1); 

virtual TLink* RemoveBefore (TLink* 1); 

virtual boolean AddAfter(TLink* 1, MCollectible* obj); 

virtual boolean AddBefore(TLink* 1, MCollectible* obj); 


TLinkedList::TLinkedList (MCollectibleCompareFn testFn); 
Create a new linked list and return it as the result. testFn is used by all methods when testing for 
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entries which match. 


TLinkedList::~TLinkedList (); 
Destroy the linked list and all the links associated with it; however, the objects in the linked list are 
not freed. (The user is responsible for the objects - the system is responsible for the links). 


long TLinkedList::Count (); 
Return the number of elements in the linked list. 


MCollectible* LinkedList::Remove (const MCollectibles obj, 

boolean removeAll=FALSE) ; 
Remove the first link which contains obj as the value of its link from the list. If removeAll=-TRUE 
then remove all links which contain obj as its value. Return the removed object. 


. 


MCollectible* LinkedList: :RemoveAfter (const MCollectible& obj); 
Remove the link after the init : tn the removed object. 


MCollectible* TLin 
Remove the object befor. 


f(const MCollectibl 
Return the removed a 


void TLinkedList: 


Remove all of the obj in the list. 


MCollectible* T: 
Remove the first obj e removed obje 


MCollectible* : 
Remove the last object 1 


n thé 


void TLinkedList: :DeleteAl1();/ 
Delete all of the links in the list. Free all of ach 
object) as well as the links used to hold the at 
oolean TLinkedhi : yllectibles 
= MCo Leet yy 
e list. If existingObj does not act 


Add obj after e 
false; otherwis 


AddBefore (const MCollectible& existin 
MCollectible* obj); 

Add obj before existingObj in the list. If existingObj does not actually exist in the list then return 

false; otherwise return true. 


boolean TLinkedList: 


void TLinkedList: :AddFirst (MCollectible* obj); 
Add obj to the front of the list in a newly created link. 


void TLinkedList: :AddLast (MCollectible* obj); 
Add the obj to the end of the list 


MCollectible* TLinkedList::After(const MCollectible& obj) const; 
Return the object after the first occurrence of obj in the list. If there is no object after obj then return 
NIL. ; 
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MCollectible* TLinkedList::Before(const MCollectible& obj) const; 
Return the object before the first occurrence of obj in the list. If there is no object before obj then 
return NIL. 


MCollectible* TLinkedList::First() const; 
Return the first object in the list. If there are no objects in the list, return NIL. 


MCollectible* TLinkedList::Last() const; 
Return the last object in the list. If there are no objects in the list, return NIL. 


void TLinkedList::Rotate (boolean firstBecomesLast=TRUE) ; 

If firstBecomesLast=TRUE, the first element in the list becomes the last element, the second 
becomes the first, the third becomes the second, and so on. If firstBecomesLast=FALSE, the last 
element becomes the first element, the first becomes the second, and so on. 


TLink* TLinkedList:: 
Whenever the TLinkedL 
default implementation ¢ 
their own kind of TLin 


NIL, MCollectible* v 
ew link, this virtual function 
Subclasses can override:th d if they want 


TLink* TLinkedLis 
Return the first link i 


?GetFirst (); 
e list. If there are no links in the list, 


TLink* TLinkedL 
Return the last link 


TLink* TLinked : 
Sets the first element of the lin ed: 


TLink* TLinkedList : :SetLast (TLink 
Sets the last element of the linked list to be 


TLink* TLinkedLi : :Remove (TLink* 
successful, retu: 
responsible for f 
using functions 
all of the links. Therefore; 


ser functions cache a link reference, they may-have. a dangling pointer. 


TLink* LinkedList: :RemoveAfter(TLink* 1); 
Remove the link after |. If lis the last link in the list or 1 is not part of the list then return NIL; 
otherwise return the deleted link. 


TLink* TLinkedList: :RemoveBefore(TLink* 1); 
Remove the link before 1. If] is the first link in the list or 1 is not part of the list then return NIL; 
otherwise return the deleted link. 


boolean TLinkedList: :AddAfter(TLink* 1, MCollectible* obj); 
Add obj after the link 1. Create a new link to contain the obj. If] is not in the list then return false; 
otherwise return true. 


bboolean TLinkedList: :AddBefore(TLink* 1, MCollectible* obj); 
Add obj before the link 1. Create a new link to contain obj. If] is not in the list then return false; 
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otherwise return true. 


TLink* TLinkedList: :FirstLink (); 
Return the first link in the list. If there are no links in the list, return NIL. 


TLink* TLinkedList::LastLink(); 
Return the last link in the list. If there are no links in the list, return NIL. 


TDoubleLinkedList 


A TDoubleLinkedList object is useful for storing lists of MCollectibles. TDoubleLinkedLists 
are particularly useful when storage requirements are unpredictable and extensive manipulation of 
the structure (insertions, deletions) i is required. Also, ru are much more efficient (in time) than 


the last accessed object in 
Before (as well as Aft 
should override the Is 


| linked list 


class TDoubleLink 


public: 

TDoubleLinked ::IsSame) ; 

virtual ~TDow 

virtual lo 

virtual MCs 

virtual MCé6TTeéeEs 

virtual MCollectible* 

virtual void 

virtual MCollectible* 

virtual MCollectible* 

virtual boolean 

virtual boolean 

virtual 

MCollectibI 

virtual iddFirst (MCollectible* 

virtual AddLast (MCollectible* obj) 

virtual MCollectible* After(const MCollectible& obj) const; 

virtual MCollectible* Before(const MCollectible& obj) const; 

virtual MCollectible* First() const; 

virtual MCollectible* Last () const; 

virtual void Rotate (boolean firstBecomesLast=TRUE) ; 
protected: 

virtual TDoubleLink* MakeNewLink (TDoubleLink* previous, 


TDoubleLink* next, 


MCollectible* value = NIL) const; 


4, Unfortunately, this caching can cause some ambiguities when multiple instances of the same 


object are in the TDoubleLinkedList. At this point this is not viewed as a problem, only a 
feature that people need to be aware of. 


Utility Classes Thursday, March 1, 1990 
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All of the methods of TDoubleLinkedList behave like their counterparts in TLinkedList. 


TTlree 


A TTree is an abstract superclass used as a baseclass for binary trees. TTrees provide some 
ordering on their members. Objects which are added to trees should be descended from 
MOrderableCollectible. Objects which are inserted into the TTree should override the 
IsEqual(), IsLessThan() and IsGreaterThan() methods. 


class TTree: public MCollectible { 


public: 
TTree(); 
virtual SQ) 
virtual it() const; 
virtual i (MOrderableCollec D5); 
virtual move (const MOrder# fectible& obj); 
virtual ; trst() const; 


virtual MOrdé¥ableCollectible* Last() const; 
virtual void RemoveAll (); 
virtual void DeleteAll (); 


virtual Member (const leCollectibles obj) 


TTree: :TTree(); S 
Create a new tree. Use testFn to dété 


3 e (const MOrderai 
EO the passed in object. : j oved from 


void TTree: :RemoveAll () 
Remove all the objects from the tree. 


void TTree: :DeleteAll () 
Delete all the objects from the tree. Also, deallocate (i.e. call the destructor) on each object in the 
tree. 


MOrderableCollectible* TTree::Member(const MOrderableCollectible& obj) const 
Returns the actual object that is in the tree if the passed in obj “IsEqual” to an object in the tree. 
Returns NIL otherwise. 


MOrderableCollectible* TTree::First() const 
Returns the first object in the tree. 
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MOrderableCollectible* TTree::Last() const 
Returns the last object in the tree. 


TBinaryTree 


A TBinaryTree is a subclass of tree. Each node in a binary tree can hold only one key object, a 
pointer to its left child and a pointer to its right child. Objects which are inserted into the 
TBinaryTree should override the IsEqual(), IsLessThan() and IsGreaterThan() methods. 
These are used internally by the TBinaryTree class. ‘ 
class TBinaryTree: public TTfree { 
public: 
TBinaryTree (MOrderableCompareFn fn=&MOrderableCollectible::IsLessThan) ; 
virtual ~TBinaryT F 


} 


TBinaryTree::TBina areFn 
mableCollectible: 
ére in the tree to perform insertion, sea A test of IsLessThan 
cts will end up to the left of the root an 
reaterThan reverses this). 


Use testF'n to determi 
means that "smaller" 
right. Using a test o 


TRedBlackTres 


A TRedBlackTreé 
balanced. This removes any worst't 
normal binary trees. Objects which a i 
IsEqual(), IsLessThan() and IsGréa an () m 
TBRedBlackTree class. : 


class TRedBlac} 
publics 
TRedBlac 
virtual - 


ee: public TBinar 


f£n=&MOrderak Shan) ; 


TRedBlackTree: :TRedBlackTree( TOrderableCompareFn 
testFn=&MOrderableCollectible: :IsLessThan) ; 

Use testF'n to determine where in the tree to perform insertion, searches, etc. (A test of IsLessThan 

means that "smaller" objects will end up to the left of the root and larger objects will end up to the 

right. Using a test of IsGreaterThan reverses this). 


THeap 


A THeap is a data structure which insures that the elements of the heap are always partially ordered 
and balanced. Because heas are only partially ordered, they can be more efficient than 
RedBlackTrees if the type of behavior that you want is to be able to add some objects to the heap and 
then remove the largest, then add some more, remove next largest, etc. Objects which are inserted 
into the THeap should override the IsEqual(), IsLessThan() and IsGreaterThan() methods. 
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const long kIinitialHeapSize; 


class Heap: public MCollectible { 
public: : 
THeap (TOrderableCompareFn testFn=&MOrderableCollectible::IsLessThan, 
long heapSize = kInitialHeapSize) ; 
virtual ~THeap (); 
virtual MOrderableCollectible* Pop(); 
virtual MOrderableCollectible* Peek() const; . 


virtual long Count () const; 

virtual void RemoveAll (); 

virtual void DeleteAll(); 

virtual void Add (MOrderableCollectible* obj); 
virtual MOrderabl] ible*x Remove (const MOrderableCollectiblesé...ob3 


virtual "(const MOrderableColle OD) 
const; 
qualityComparisonF, 


‘sonFunction (MCox: 


virtual 
virtual 


LeCompareFn fn); 


ble::IsLessThan) ; 


A test of IsLessThan 
bs 4 


THeap: :THeap (TOr<¢ eFn testFn=&MOrdera 


MOrderableCollectibié 
Remove the object at the top of thé 


MOrderableCollectible* THeap: :Pees 
Return the object at the top of the heap. Th 


long THeap::Co const 


Return a count | 


) 


void THeap: 
Add obj to the heap: 


MOrderableCollectible* THeap::Remove (const MOrderableCollectibleé& obj) 
Remove obj from the heap. Return the actual object removed (which may not be the same as the 
object passed in only “is equal”) or NIL if no object was removed. 


MOrderableCollectible* THeap: :Member (const MOrderableCollectible& obj) const 
Return true if obj is in the heap. 


void THeap: : RemoveAll () 
Remove all the objects from the heap. 


void THeap: :DeleteAll() 
Remove all the objects from the heap. Also, deallocate (i.e. call the destructor) on each object in the 
tree. 
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MCollectibleCompareFn THeap: :GetEqualityComparisonFunction() const 
Return the equality comparison function being used by the heap. 


void THeap: :SetEqualityComparisonFunction (MCollectibleCompareFn) 
Set which member function to call as the equality comparison function when removing objects from 


the queue, checking to see whether a given object is a member, etc. This defaults to IsEqual. Most 
of the time you won’t want to change this. 


TGraphs ‘ 


A TGraph provides an abstract superclass for all graphs. Objects which are inserted into the graph 
should override the Hash() method and the IsSame() method. These are used internally by the 
graph class. 


const long kExpect 
const long kExpecte 
class TGraph: publz# 
public: . 
TGraph( const Ek 
const 

virtual ~TGra 
virtual bool 
virtual void 
virtual void 


an replace = TRUE) ; 


virtual voi 


virtual TQueue* ShortestP 


MCol?: 
virtual void DepthFirstEac ; : . 
virtual void BreadthFirstE ‘ ' L); 


virtual boolean 
} 


IsComplete (); 


TGraph ( const 
Create a new grap] 
edges, providing a gu p ced number of vertices and the pected:a 
edges from each vertex could greatly i improve the efficiency of graph operations. 


~TGraph (); 
Delete the graph and all the vertices and edges associated with the graph. 


boolean TGraph: :AddVertex (MCollectible* vertex, boolean replace) ; 
Add vertex to this. If vertex already exists in the graph and replace = TRUE then delete the old 
vertex and add the new vertex. 


void TGraph: :RemoveVertex (MCollectible* vertex); 
Remove vertex from this. 


void TGraph: :AddEdge (MCollectible*. from, MCollectible* to, WeightType weight) ; 
Add the edge to the graph. 
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void TGraph: :RemoveEdge (MCollectible* from, MCollectible* to, WeightType 
weight); 
Remove the edge from the graph. 


TQueue* TGraph: :ShortestPath (MCollectible* vertexl, MCollectible* vertex2); 
Return the path in the graph connecting vertex1 and vertex2 with the property that the sum of the 
weights of the edges is minimized over all such paths. Each RemoveFirst operation on the queue 
will remove edges starting at vertex1 and moving to vertex2. The user is responsible for freeing this 
queue of vertices and edges when it is no longer needed. 


void TGraph::DepthFirstEach(TVertexActionFn fn, TQueue* start=NIL); 
Iterate over all of the vertices in the graph reachable from the start collection in a depth-first 
fashion. Apply fn to each vertex in the graph in this order. If start=NIL then an appropriate 
starting set of vertices will be chosen. 


fonFn fn, TQueue* start) ;.. 
from the start collection in. 
is order. If start=NIL then: 


void TGraph: :Breadth. 
Iterate over all of the vert: 
fashion. Apply fn to eac 
starting set of vertices 


propriate 


boolean TGraph::T: 
Return true if there is: 


mplete (); 
edge from every vertex to every other y¥: 


TUndirectedGr 


A TUndirectedGraph pri 
inserted into the graph should 6vé 
used internally by the graph class. 


class TUndirectedGraph: public TGr 


public: 
TUndirectedGraph(const long ver Orvertic 
: 7 imbe rOfEd ex) ; 
virtual 
virtual 


virtual ba 
virtual TSet*:: Fol ctedComponents() ; 
virtual TDeque* ConnectedComponents () ; 
virtual TSet* ArticulationPoints (); 
virtual boolean IsBiconnected(); 


} 


TUndirectedGraph: :TUndirectedGraph (const long vertices, const long edges); 
Create a new graph. While the graph which is returned could contain any number of vertices and 
edges, providing a guess as to the expected number of vertices and the expected average number of 
edges from each vertex could greatly improve the efficiency of graph operations. 


~TUndirectedGraph: :TUndirectedGraph (); 
Delete the graph and all the vertices and edges associated with the graph. All edges and 
vertices are freed. 
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TSet* TUndirectedGraph: :MinimumSpanningTree(); 

Return a set of edges which represents a minimum spanning tree of a weighted graph. A minimum 
spanning tree is a collection of edges that connects all the vertices such that the sum of the weights 
of the edges is at least as small as the sum of the weights of any other collection of edges that 
connects all the vertices. (Real life: I want to wire a group of cities so that each city can reach each 
other city and I want to minimize the amount of wire to use.) The user is responsible for freeing this 
set of vertices and edges when it is no longer needed. 


boolean TUndirectedGraph: :IsConnected(); 
Return true if this is connected. A graph is connected if there is a path from every vertex in the 
graph to every other vertex in the graph. : 


TSet* TUndirectedGraph: :BiconnectedComponents (); 
Return a collection of biconnected components of this. Each object in the set is itself a graph. 
Biconnected components of a graph are sets of vertices mutually accessible via two distinct points. 
The user is responsible fo f vertices when it is no longer need 


TDeque* TUndirecte 
Return a collection of co; 
which represents a conn 
TDeque of vertices an 


onents (); 
. Each object in the T 
r ph. The user is res 
ges when it is no longer needed. 


tself a TDeque 
2 r freeing this 


TSet* TUndirecte 
Return a collection o 
articulation point (s¢ i 
there are distinct v. fr y pat 
biconnected graph. : 
freeing the returnéd' set of ve} 


ArticulationPoints () ; 
ertex oe is an 


boolean TUndirectedGraph: :IsBic¢ 
Return true if this is biconnected. A graph: 
different paths connecting each pair of verti 
are removed, the graph is still connected. (Ki 
that a failure along one point does not leave ¢ 


and all the 
twork to b 


DirectedGr 


A TDirectedGraph provides an implementation for a directed graph. Obj which are inserted 
into the graph should override the Hash() method and the IsSame() method. These are used 
internally by the graph class. 


class TDirectedGraph: public TGraph { 
public: 
TDirectedGraph({ const long vertices=kExpectedNumberOfVertices, 
const long edges=kExpectedAverageNumberOfEdgesPerVertex) ; 
virtual ~TDirectedGraph (); 
virtual TQueue* TopologicalSort (TQueue* start=NIL) ; 
virtual TSet* StronglyConnectedComponents () ; 
virtual boolean IsStronglyConnected () ; 
virtual boolean IsWeaklyConnected () ; 
virtual boolean IsAcyclic();- 
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TDirectedGraph: :TDirectedGraph (const long vertices, const long edges) ; 

Create a new directed graph (digraph). While the graph which is returned could contain any number 
of vertices and edges, providing a guess as to the expected number of vertices and the expected 
average number of edges from each vertex could greatly improve the efficiency of graph operations. 


~TDirectedGraph: :TDirectedGraph(); 

Delete the graph and all the vertices and edges associated with the graph. All edges and 

vertices are freed. 

TQueue* TDirectedGraph: :TopologicalSort (const TQueue* start=NIL); 

Return an ordering on this such that no vertex in the ordering is before any vertex that points to it. 
Each object in the queue is a vertex. Use the start queue as the vertices to begin the topological sort. 
If no start queue is provided then some appropriate set of starting nodes will be chosen. (The 
appropriate set of nodes will consist of all nodes of in-degree zero) Note that there is sibl 
to perform a topological t a directed acyclic graph (DAGY: 
NIL would be returned.. 
needed. 


TSet* TDirectedGr 
Return a collection o 
the set is itself a Dir 
there is a path from: 
of graphs when it i 
components in topx 


ah: : gly onnectedComponents ( 
rongly connected components of this. Ea 
dGraph. (Strongly connected compon 


onnected component in 
h are subgraphs in which 
onsible for freeing this set 


boolean TDireét at 
A graph is strongly connecte 
may only be traversed from tail to hea 


boolean TDirectedGraph: :IsWeaklyC 
A digraph is weakly connected if for every pa y 
may be traversed ) tail - i.e. it was d for 


Random Numbers 


TRandomNumberGenerator generates a sequence of pseudo random numbers given an initial seed. 
If no initial seed is specified, the system time is used as a seed. The range of random number values 
is [0, 2431-1>. 


class TRandomNumberGenerator { 

public: 
TRandomNumberGenerator(); 
TRandomNumberGenerator(long initialSeed) ; 
~TRandomNumberGenerator(); 
long Next(); 
void Reset(); 

“long First(); 
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protected: 
long GetSeed(); 
void SetSeed(long newInitialSeed) ; 
}; 


TRandomNumberGenerator: :TRandomNumberGenerator() 
Construct a new random number generator. Use the system time as a seed value. 


TRandomNumberGenerator: :TRandomNumberGenerator (long initialSeed) 
Construct a new random number generator using initialSeed as the seed. 


TRandomNumberGenerator: :~TRandomNumberGenerator() 
Destroy the random number generator. 


long TRandomNumberGe: 
Return the next random 


long TRandomNumbe 
Equivalent to Reset ()} 


void TRandomNumb 


Reset the random nu > of random numbers. 


long TRandomNum 
Get the initial seed 


void TRandomNumbe rGenérate 
Set the seed used by the random numb 


@ Registered /Restricted Utility Classes Thursday, March 1, 1990 2.1.2 - 34 


Advanced Topics 
Iterators 


Earlier versions of the utility classes included an "Each" mechanism for iterating over the objects in 
a class. Unfortunately, there are a number of problems with this mechanism (difficult to pass back 
information and no closures in C++) that facilitate the need for a more generic mechanism. 


All of the classes described in the document have iterator classes defined for them. An iterator for a 
particular object will iterate over all of the objects in aclass. For example, the TLinkedListIterator 
will iterate over each element in the TLinkedList class. Each call to the iterator will return the next 
element in the class. For example: 


TLinkedList alist = new TLinkedList (); 
// Some linked lis 
TLinkedListIterato 
MCollectible* foo: 
while (foo != NI 
{ 


nkedListIterator (ali 


// do something = 
foo = 


the next object 
ch, Member, 
if some el 


could be: 


TIterator* i = Iterator(); 
MCollectible* e; 
boolean done = false; 


false) ) 


done = (e->*fn) (some arguments....); 
e = i->Next (); 


delete i; 
} 


return done; 
} 


Objects in the class will be returned with order preserved if the class contains objects which are fully 
ordered. For example, linked lists, deques, queues, stacks, binary trees, etc. will return objects “in 
order." Hashtables, sets, bags, dictionaries, heaps, priority queues etc. will return objects in some 
random (at least to the user) order. 


Operations on the collection itself will invalidate all outstanding iterators on the collection until the 
iterator resyncs with the collection. This occurs in the calls First and Last. Starting with dll 


# Registered /Restricted Utility Classes Thursday, March 1, 1990 2.1.2 - 35 


Pink, you can remove an element from the collection using a method of the iterator (Remove). This 
automatically resyncs the iterator to the collection; however, all other iterators are invalidated just 
as if any operation was done to the collection they are tied to. 


class TIterator { 

public: 
TIterator(); 
virtual ~TIterator(); 
virtual MCollectible* First ()? 
virtual MCollectible* Next (); 
virtual MCollectible* Remove () ; 

; 


Titerator::TIterator() 
Create a new iterator. 


Titerator::~TItera 
Delete the iterator. 


MCollectible* TIt 
Reset the iterator an 


collection if other opé 


turn the first element of the collection. ‘the iterator to the 


ons on the collection caused the iterator 


MCollectible* Tf 
Remove the curren! 
way to remove an. ile iterating. 
if any change to the 


use of the Remove method of thi 
FAIL. 


MCollectible* TIterator: :Next () 
Retrieve the next object in the collection an mit. Thé 
order that reflects the “ordered-ness” of the ¢ i 
elements). If the¢ollection has changed (0 
iterator) since ¢ First was call 


Subclasses of TS 
collection in “backwar« 


4 SequenceIterator for 
rather than the usual order. 


class TSequenceIterator : public TIterator { 
public: 
TSequencelIterator(); 
virtual ~TSequencelIterator(); 
virtual MCollectible* Last (); 
virtual MCollectible* Previous (); 
} 


TSequencelIterator: :TSequencelIterator () 
Create a new iterator. 


TSequencelIterator: :~TSequencelIterator () 
Delete the iterator. 
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MCollectible* TSequenceIterator: :Last () 
Return the last object in the collection. This resyncs the iterator to the collection if other operations 


on the collection caused the iterator to be invalidated. 


MCollectible* TSequencelterator:: Previous () 

Retrieve the previous object in the collection and return it. The order that anjects are retrieved is in 
an order that reflects the “ordered-ness” of the collection (or the lack of ordering on the collection 
elements). If the collection has changed (other than through the use of the Remove method of this 
iterator) since the last time First or Last was called, this method will FAIL. 


. 


Garbage Collection 


The role of automatic storage management in the C++ world is a very controversial issue. Ina 

recent paper, “Possible Directions-for.G+-+, Stroustrup states that garbage collectors and : 
probably not a good fit. § i 
collection techniques per 


come to expect from G 


Stroustrup adds tha 
giving the programy 

“garbage collected 
tone) of automatic storage with 
alludes to some work being done bt 
pointer is an object that acts like a p 
counted pointer to an object is destroyed, t 
count garbage collector). 


Earlier versions of the : 
classes. This is.ric fat failed. ; tion is 
unimportant; i Snot : 
the usability ae 


As it stands now, users of these classes should take great care with respect'to memory management. 
In general, the utility classes manage their own memory and never allocate memory that they expect 
the user to manage.” Likewise, objects created by the user and put into collections should be 
managed by that user. A common error that many people encounter is the following: 


TSet* aSet = new TSet (); 
TSurrogateTask* aTask = new TSurrogateTask(); 
aSet->Add (aTask) ; 


.-much later.. 


5. The major exception to this rule is the member function, Iterator (), which creates a new 
iterator on the heap that it expects the user to manage. If you don’t need the polymorphism 
(that is, you know the type of the collection as something other than TCollection), you can 

. create an iterator directly as in TDequeIterator anIterator (&aDeque). 
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TSurrogateTask* bTask = new TSurrogateTask(); 
// »Task is equal to aTask but not the same object 


// The wrong way unless you know bTask is pointer eq to aTask 
aSet~>Remove (bTask) ; 
delete bTask; 


// The right way in general 
TSurrogateTask* someTask = (TSurrogateTask*) aSet~>Remove (bTask) ; 
if (someTask != bTask) 
delete someTask; 
delete bTask; 


Dictionaries are slightly more complicated to deal with because you always receive the old value 
back from the call to Remove. This’ means eeu tne pointer to the key is dropped on the floor by the 


utility classes. Use the Déteé sey, value pair, delete the key 
value to the caller. 
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cheeetah n. 1. A long-legged, swift running wild cat, 
Acinonyx jubatus, of Africa and southwestern Asia, 
that has black spotted, tawny fur and nonretractile 
claws and is sometimes trained to pursue game. 2. 
Cheap persistent objects for Pink. | 
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Introduction 


cheetah is a set of classes and protocol for use with C++ in the Pink world for saving and restoring objects 
to and froma stream. Objects which descend from the appropriate classes and adhere to the proper 
protocol can be “flattened” to a stream (memory, a disk file, the network, etc.) and “expanded” on the 
other end. 


Objects with references to other objects can be flattened and restored easily. Multiple references to the 
same object are restored properly. Circular references are also handled in the design of the system. Sets 
of objects can be flattened and restored together and repeated references are handled efficiently. cheetah 
does not address where objects are stored, how they are found, indexing into a database of objects, of 
garbage collection of persistent objects. 


Architecture Overview 


Converting objects to a “fl ature for an Se oriented progté 
It allows objects to have a 3 
provides a set of classes aj 
of objects from classes d 
global function, Flatte 
referenced by this ob} 
disk, sent to another 
which takes a flattene 


© object and all objects 
which can be stored on 


is process results in a linearized form o 
etc The r reverse of this process is to use 


The architecture of 
ephemeral (in the ca 
concern) as well as-efficien 
object when generating a flattened for 
designers to provide hints to the system con 
class designer knows that the structure of an’ 
the object and all the objects that the object po 
designer could tell the system this. 


Details 


TStream 


The TSt ream class provides an abstract protocol for reading and writing data structures. The stream can 
be a section of memory, an Opus Message, a disk file or anything else that allows binary representations 
of objects to be written to it. TSt ream is an abstract superclass. Derived classes of TSt ream should 
implement the protocol of TStream. All of the methods in TSt ream signal exceptions when bad things 
happen (for example, end of file is reached). All of the read/write methods use a buffered approach for 
reading and writing. Virtual functions are called when the buffer is full or empty at which time your 
stream can do whatever processing it needs. If no buffering is desired, the size of the buffer can be set to 
zero and your virtual functions will be called at every read or write. This design allows the code for 
reading and writing to be inline and efficient (no function calls to write or read froma stream except at 
overflow or underflow) while also allowing streams to have some virtual behavior. 
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typedef size_t StreamPosition; 


class TStream : public MCollectible { 
public: 
virtual ~TStream(); 


// Non virtual reads and writes for all the primitive types: 
// char, short, long (signed and unsigned), float, extended, double, etc. 


virtual void Reset () ; 

virtual StreamPosition Position (); : 
virtual void Seek (StreamPosition position) ; 

virtual void SeekRelative (StreamPosition amount) ; 

virtual StreamPosition GetLogicalEndOfStream() ; 

virtual StreamPosition GetPhysicalEndOfStream() ; 

virtual SEC: 


virtual 
virtual 
virtual 
virtual 
virtual TDequeé 
virtual void 
virtual Boole 


GetDeferredWriteList 
SetForceFlattenEterné (Boolean) ; 
GetForceFlattenEter 


protected: 
TStream (void 
virtual voz 
virtual voi 
void* 

void 

void 
StreamPosition 
void 


TStream& operator<<=(char* c, TStream& s); 
TStream& operator<<=(long& c, TStream& s); 
TStream& operator<<=(short& c, TStreamé& s); 
TStream& operator<<=(char& c, TStreamé s); 
TStream& operator<<=(Boolean& c, TStreamé s); 


Overloaded operators for writing (you don’t need to override these - in fact, you can’t): 
TStream& operator>>=(const char* c, TStream& s); 

TStream& operator>>=(const long& c, TStreamé& s); 

TStream& operator>>=(const shorté& c, TStream& s); 

TStream& operator>>=(const char& c, TStream& s); 

TStream& operator>>=(const Boolean& c, TStream& s); 


, 
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TStream::TStream(void* bufferStart, StreamPosition howmuch) 
You must pass the start of a buffer to use as well as the size of the buffer when creating stream objects. 
This buffer will be used for reading and writing. Subclasses will not necessarily export this information 


to their clients. To specify no buffering, passing NIL, 0 will work. 


void TStream: : Reset () 
Reset the stream. The current position is set to zero. 


StreamPosition TStream: :Position () 
Return the current position of the stream. 


void TStream: :Seek(StreamPosition position) . 
Seek to the specified position. The next read or write will take place from there. 


void TStream: :SeekRelat 
Seek (relative to where yo 
there. 


tLreame. 


ef 


a, position) 
tnt. The next read or write will ta 


StreamPosition TSt: 


could not be proces ase: ; 
(location, count) should be processed: the 
buffer length and current buffer start s 


void TStream: :BufferEmpty (void*, 
This routine is called by cheetah when the spect 
data to process a request. Appropriate action 

etc.). Furthermore; equest which couldn’t 
and current buffe auld be set appropri 


rocessed show. 
Ly upon exit. 


void TStream: 
TContext* TStream ) : 

Set/Get the context used i g or writing objects to the stream. It is only necessary to set the context 
when writing a set of objects which has multiple references to the same objects. 


void TStream: :SetDeepF reeze (Boolean) 

Boolean TStream: :GetDeepF reeze () 

Set/Get the “deepFreeze” used in reading or writing objects to the stream. If GetDeepFreeze returns 
FALSE, tokens are used to represent the class name. If GetDeepF reeze returns TRUE, strings are used. 
When flattening objects which will persist across sessions or machines, Get DeepFreeze should return 
TRUE. 


void TStream: :SetDeferredWriteList (TDeque*) 


TDeque* TStream::GetDeferredWriteList() const 
This list is used internally by the cheetah system. 
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void TStream: :SetForceFlattenEternalObjects (Boolean) 

Boolean TStream::GetForceFlattenEternalObjects() const 

Set/Get the flag that determines whether “eternal” objects will be treated as if they were ordinary objects 
when writing to the stream. If the flag is true, “eternal” object references are flattened on the stream 
much like an ordinary object. If the flag is false, “eternal” object references are noted in the stream and 
the “eternal” object is written to where it belongs. More on this in the section on eternal objects. 


void* TStream: :GetBufferStart() const 

void TStream: :SetBufferStart (void*) 

void TStream::IncrementBufferStart (StreamPosition) 
StreamPosition TStream::GetBufferLength() const . 
void TStream: :SetBufferLength (StreamPosition) 

void TStream: :DecrementBufferLength (StreamPosition) 

void TStream: :SetBufferWasModified(Boolean modified=TRUE) 

Boolean TStream: :GetBufferWasModified() const 

These routines perform operations on the current buffer start pointer and buffer length pointer.that.are 
used to determine where ‘tten. These setters/getters should:ti “inthe 
BufferFull/BufferEmpty r inter /length before exiting... 


Global Functions 


There are two function the system which can be used to flatten, a 


void FlattenPoi 
To flatten an object 
object to is passed | 
stream, set the conté 
argument is used in the case whére't 
stream. The TContext is basically a dyna 
assign references to repeated object instancé 
object is to be saved, the TContext can be gét 
multiple objects (which might point to overlap 
provide a TContext. For example: 


// FlattenPointer two objects with shared parts 
TPersistentClassD* d = new TPersistentClassD("me", "cguy", “BOUY " y. -a) 
TMemoryStream pneuma2 (new char[(100], 100); 

TContext tim; 

pneuma2->SetContext (&tim) ; 

FlattenPointer(d, &pneuma2) ; 

FlattenPointer(a, &pneuma2) ; 

pneuma2->SetContext (NIL) ; 


Streams also provide information about whether they are ephemeral (in the case of a memory stream) or 
more persistent (as in a disk file). A deepFreeze attribute of the stream is set to true if the flattening 
should store the object in its most general form; that is, a form which can be resurrected on another CPU 
or saved to disk and resurrected. Objects which are simply sent to another team (for example, inan 
Opus/2 message) can use a more compact representation. See the examples section for code which saves 
single objects and multiple objects. Note that in any event, the original object is unchanged by the 
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process of flattening. The stream has the flattened version of the object at the time of the snapshot. 


MCollectible* Resurrect (TStream* fromwhere) ; 
The Resurrect function will take the flattened form of an object and create an MCollect ible object 
from it. The stream which is passed in contains the flattened form of the object. The context which is 
passed in is used in the same manner as above. For example, to resurrect the two objects created in the 
example above: 

// Resurrect a single object 

TPersistentClassA* A; 

pneumal->Reset (); 

A = (TPersistentClassA*) Resurrect (pneumal) ; 


// Resurrect multiple objects from the same stream 
TPersistentClassD* D; 

pneuma2->Reset 
TContext conte 
pneuma2->SetcC 


=t (pneuma2) ; 
st (oneuma2) ; 


It is of the utmost imperté order of flattening exactly 


MCollectible 


MCollectible should be mixed { dle i ‘ ble 
provides a general mechanism for readin 


It is only necessary to be a subclass of MCollex s of 


that class directly. Classes with base classes or 
MCollectiblec ill be flattened and resu 
operator>>=a 
descending from 
object, must, of ce: 
requires calls to F: 


ran 


stible 


urrecting t cts 


surrect). 
typedef TokenID ClassName; 


class MCollectible! { 
public: 
MCollectible(); 
virtual ~MCollectible(); 


virtual TStreamé& ‘operator>>=(TStream& towhere) ; 

virtual TStreams& operator<<=(TStream& towhere) ; 

virtual StreamPosition Size (TContext* tim = NIL, Boolean deepFreeze = 
FALSE) ; 

virtual ClassName GetClassNameAsToken (); 


virtual char* GetClassNameAsString(); 


1. This is the part of MCollectible concerned with flattening objects to a stream and resurrecting them 
later. For more information about MCollectible, see the Utility Classes document. 
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virtual Boolean StructureDoesNotHaveRepeatedReferences (Boolean 
deepFreeze = FALSE); 


// These methods will be discussed later with MEternal. 


virtual ObjectID GetObjectID() const; 

virtual void SetObjectID (Object ID) ; 

virtual TPersistentContext* GetPersistentContext() const; 

virtual void SetPersistentContext (TPersistentContext*) ; 
virtual Boolean GetDirty() const; 

virtual void SetDirty (Boolean dirty = TRUE); 


ja | > 


Note: When subclassing from MCollectible, include the line: 


MCollectibleDeclarationsMacro (myClassName) ; 
in the declaration of your class and the line: 


MCollectibleDefini 
in your .c file. 


TStream& MCollecti 
This is a workhorse rout: 
expand method is call 
from its flattened form: 
of class D, has a mem 
look like: 
TStreamé& stream* fromwhe 


{ 


eam* fromwhere) 
object must have a 


y the Resurrect procedure as well as direet 
r example, if class C is descended from cl 
‘long, a member char, and a pointer to an 


‘this one. This 


ser to restore an object 
B, has a member object d 


Ss Expand routine would 


B: :Operats: 
d.operator<<= (from 

fLong <<= fromwhere; 
fChar <<= fromwhere; : 
e = (E*) Resurrect (fromwh 
return fromwhere; 


; pSt ream* towhé 
tifinie must flatten the bi 


jects. Finally, it must flatten its membe 
Simple data types are flattened by writing the 
(using the stream: :Write() member function). References to other objects are flattened by recursively 


calling the FlattenPointer routine with the parameters which were passed in. For example, if class C 
is descended from classes A and B, has a member object d of class D, has a member long, a member char, 


and a pointer to an E object (e) , its Flatten routine would look like: 


TStream& C::operator>>=(TStream* towhere) 
{ 


A: :operator>>=(towhere) ; 
B::operator>>=(towhere) ; 
d.operator>>=(towhere); 
fLong >>= towhere; 

fChar >>= towhere; 
FlattenPointer(e, towhere); 
return towhere; . 
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StreamPosition MeOLie ceo te nam aes pCOnrext” tim = NIL, Boolean deepFreeze = 
FALSE) 

This method returns the size that this object will be when it is flattened in the passed in context. This 
routine should probably not be overridden except by the most stalwart subclasses. This is a very 
expensive method to call because cheetah needs to flatten the object in order to determine its size. If you 
are going to be flattening the object anyway, a better way of determining the size is to reserve space in the 
stream for the size of the object, flatten the object, note the position, seek back to where the size goes, 
compute the size (you know the final position and the initial position), and stream it. 


const char* MCollectible: :GetClassNameAsString() 
Return the name of the class as a string. 


ClassName MCollectible: :GetClassNameAsToken () 
The default version of this routine calls the GetClassNameAsString command, then asks the token 

manager for the token that matches this class. Subclasses can override this method to cache the.to 
This routine actually retu This will be changed sometime afte 


Boolean MCollectib 


This routine returns tru 
circular reference to itse 
you don’t know whet 


uring flattening. If 
f, is the default). 


TContext 


TContext isa class is 
these routines or ever create anything oth ted 
by passing zero arguments to the constru 


typedef long LocalObjectNun 


class TContex, 
private: 
TDictiona 
Boolean ~ 
public: 
TContext (Boolean multipleObjectContext = TRUE); 
virtual ~TContext(); 


sEContext ; 


virtual long Count (); 

virtual MCollectible* Find (LocalObjectNumber) ; 

virtual LocalObjectNumber Add(MCollectible*, Boolean& newentry) ; 

virtual MCollectible* Replace (MCollectible* newobject, 
LocalObjectNumber fred); 

virtual Boolean GetMultipleObjectContext () ; 
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Eternal Objects 


The data management tools in the toolbax provide methods for the rapid retrieval of an arbitrary object 
given an arbitrary key. cheetah specifies the external data format for an object. The integration of the 
data management tools with cheetah provide for a simple persistent object system in which objects can be 
individualy addressed and brought into memory. A TPersistentContext is a pool of objects in which 
any object can be found and mapped into memory given its object id. Objects which live ina 
TPersistentContext have MEternal asa mixin. When FlattenPointer is called on an “eternal” 
object, a reference to the eternal object is put in the stream rather than the flattened version of the object 
itself. The eternal object (if dirty) is flushed to the TPersistentContext at this time. When ; 
Resurrect is called on a stream which contains a reference to an eternal object, the object is returned if 
already in memory or loaded from the TPersistentContext if not. 


Designing a class of objects which mixin MEternal involves a number of additional decisions for the 
class designer. First, pointers to ordinary o 
operator>>= routine of the objectuntess: accopyot the pr 
an eternal object is read ba¢ 
may or may not be aroun 
thus the use of the norma! 
way to guarantee consisté 


y object which existed at the ti 
# the pool of eternal objects:st 
ealing with ordinary « 
context mechanism, tf 


referenced objects ar 
solve this problem n 


ME ternal 


Eternal objects are just like ordinary objects wi 
mixin are flattened to a stream, only a referenc 
assumed that the MEt.erna1 object can be loade 
presumably has a¢ c 4 
flattened” on stré 
will not be “the 
object is part of, 
objectid, ask the TPersiste: 
TPersistentContext, ask the TPersistentContext to delete it.2 Deleting the object in memory has 
no effect on the object in the TPersistentContext. If a change is made to an MEternal object and 
you would like to have that change reflected in the TRersistentContext, two things must be done. 
First, mark the object as dirty using the SetDirty virtual function. Second, either explicitly flush it to 


the context by calling the virtual function Add again or implicitly have it flushed by flattening the object 
to a stream (or flattening an object that references it). 


2. Note that no guarantees are made that deleting an object from a TPersistentContext is safe - that is, 
other objects might reference it and will now have a dangling reference. The problems of garbage 
collection across pools of persistent objects would be nice but I don’t have the time or desire to spend 

' the next ten years of my life on a research project. 
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#define MEternalMacro() \ 


{ MEternal::SetPersistentContext (pc) ;}; 
virtual Boolean GetDirty() const 

{ return MEternal::GetDirty();}; 
virtual void SetDirty (Boolean dirty = TRUE) 

{ MEternal::SetDirty (dirty) ;} 


virtual ObjectID GetObjectID() const \ 
{ return MEternal: :GetObjectID();}; \ 
virtual void SetObjectID(ObjectID id) \ 
{ MEternal::SetObjectID(id);}; ; ‘ 

virtual TPersistentContext* GetPersistentContext() const \ 
{ return MEternal::GetPersistentContext ();}; ‘ 

virtual void SetPersistentContext (TPersistentContext* pc) \ 
\ 

‘ 

\ 

\ 


Class MEternal { 


public: 
virtual ~MEterna 
Objectf eCtiID()) const: 
AectID (ObjectID 
“PersistentContext 
SetPersistentConteé: istentContext*) ; 
Be ee GetDirty() consts 
SetDirty (Boole TRUE) ; 
virtual .. operator>>= (TS! 
virtual 
protected: 


MEternal (ObjectID 
hi 


Note: When subclassing from MEternal, in 

MEternalMacro(); : 
in the declaration of your class to automaticall 
with the help of the MEt.ernal mixin. 


A TPersistentContext is a collection of MEternal objects that can be individually accessed and 
retrieved. MEternal objects in one context can reference objects in another persistent context. The 
retrievel of objects from a persistent context is via an objectid which is automatically assigned at the time 
of insertion. If it is desired, a mapping could be provided from a “name” to an objectid at a higher level 
(using the datamanagement tools). Deleting a TPersistentContext only removes it from memory. 
Throwing away the file (the “real” persistent context) will really destroy the persistent context. 


class TPersistentContext : public MCollectible { 
public: 
TPersistentContext (char* contextName) ; 
virtual ~TPersistentContext (); 
virtual MCollectible* Retrieve (ObjectID); 


virtual void Add (MCollectible*) ; 
virtual void Remove (Object ID) ; 
virtual void Delete (ObjectID); 
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virtual Boolean IsEqual (const MCollectible* obj); 
virtual long Hash (); 
virtual char* GetName (); 


// These routines are used internally by cheetah 
virtual void DeferredAdd(MCollectible* objAsEternal, TDeque*) ; 
virtual void CommitDeferredRequest (TEternalWrapper*) ; 


re 


TPersistentContext: :TPersistentContext (char* contextName) 
Create a new persistent context or open an existing persistent context named contextName. 


TPersistentContext: :~TPersistentContext () 
Destroy the object in memory currently that manages the persistent context. 


MCollectible* TPersi 


Lave (ObjectID objectID) 
Retrieve the object named: 


it context. 


void TPersistentCo 
Add (or update) the eté 
passing an object whic 


‘le* ete roar. 
object ID is assi 
oes not have MEternal as a mixin will result 


ject. Note that 
me exception. 


void TPersisten 
Remove the object n 
to clean up the refere 


mtext: :Remove (Object ID objectI] 
bjectLD.from the persistent context. F 
dees not “delete” the o 


vy the MEternal destructor 


Delete the object ni 
delete it from disk. 


Example use of Eternal Object 


class TArnKey 

public: 
TArnKey (: 
~TArnKey: 
virtual 
virtual TStre 
virtual Boolean 
virtual long Hash (); 

const TTexté GetText (); 
more virtual functions... 

MCollectibleDeclarationsMacro(TArnKey) ; 
MEternalMacro(); 

private: 
TText £Text; 
MCollectible* fNextOne; 


public MCollectibl 


ke 


MCollectibleDefinitionsMacro (TArnKey) ; 
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TArnKey::TArnKey(const TText& someText, MCollectible* nextOne) 
TText (someText) 
{ 
fNextOne = nextOne; 
SetDirty(); 
} 


TArnKey: :~TArnKey () 
{ 
} 


TStream& TArnKey::operator>>=(TStream& towhere) 
{ 
MCollectible: :operator>>=(towhere) ; 


fText >>= towhere;. 
FlattenPointer (fNé 
return towhere; 


TStream& TArnKey :fQperator<<=(TStream& fromwhere) 


MCollectible: :; tors<=(fromwhere) ; 
MEternal: :oper: 
fText <<= fro 
fNextOne = Re 
return fromwhexe; 


const TText& TArnKey: :GetText () 
{ 


return fText; 


Boolean TAL aC ectible* o 
{ 


return fTe 


long TArnKey: :Hash () 
{ 
return fText.Hash(); 


main () 

{ 
TArnKey* aKey = new TArnKey (“hello”); 
TArnKey* bKey = new TArnKey(“goodbye”, aKey); 
TPersistentContext someContext (“myContext”) ; 


someContext .Add (aKey) ; // aKey added to persistent context. assume 
// objID = 1 for this example 

-someContext .Add(bKey) ; // bKey added to persistent context - with 
// a reference to aKey. assume objID = 2 for 
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// this example 
delete aKkey; 
delete bKey; . // Removes in memory versions 


TArnKey* retval2 = someContext .Retrieve (2) ; 

// Loads in both aKey and bKey and restores 
// references properly. Note that aKey was read 
// in at this point even though it hasn’t 
// been referenced in any code. Look at next 
// example to see how fNextOne field could _ 
// be declared in TArnKey to make aKey loaded 
// only when referenced. 

} 


And now, another example using @ a smart pointes to force objects to be demand loaded (rather than all 
referenced objects being loaded: :is loaded). : 


class TSmartPointe 
public: 

TSmartPointer ( 

TSmartPointer ( 


Mectibles E ecaionGace = NIL); 
operator->() 
operator MCo 


virtual 
virtual 
virtual 
virtual void 
virtual TPersistentCon 
virtual void 
MCollectible* 
void 
MCollectibleDeclarationsMacro 


(TPersis aa We 


private: 
MCollec 
ObjectID®* 


tentContext; 


MCollectibleDefinitionsMacro(TSmartPointer); 


TSmartPointer: :TSmartPointer(ObjectID objID, TPersistentContext* pc) 
{ 

fObjectID = objID; 

fPersistentContext = pc; 

fRealObject = NIL; 
} 


TSmartPointer:.:TSmartPointer (MCollectible* realObject) 
{ 

fRealObject = realObject; 

fPersistentContext = fRealObject- ->GetPersistentContext (); 
‘fObjectID = fRealObject->GetObjectID() ; 
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MCollectible* TSmartPointer: :operator->() 
{ 
return GetRealObject (); 


} 


TSmartPointer::operator MCollectible* () 


return GetRealObject(); 


} 


void TSmartPointer: :operator=(MCollectible* realObject) 
{ 

SetRealObject (realObject) ; 
} 


const unsigned char 
const unsigned cha 


TStream& TSmartPoititer: :operator>>=(TStream& towhers 


MCollectible::oa 
if (fPersisten 


catlor>> 


(towhere) ; 


kNotEternal 


kYesEternal >>= towhere; 


// This forces a flush. 
GetPersist ect); 


return towhere; 


TStream& TSmartPointer: :operator<<=(TStream& fromwhere) 


{ 
MCollectible: :operator<<=(fromwhere) ; 


unsigned char delimiter = 0; 
delimiter <<= fromwhere; 
if (delimiter == kNotEternal) 


{ 
fRealObject = Resurrect (fromwhere) ; 
} 


else 


{ 
fObjectID <<= fromwhere; 
fPersistentContext = new TPersistentContext (); 
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*xfPersistentContext <<= fromwhere; 
} 


return fromwhere; 


} 


ObjectID TSmartPointer::GetObjectID() const 
{ 


if ((fRealObject !'!= NIL) && (GetPersistentContext() != NIL)) 
return fRealObject~->GetObjectID (); 
else 


return fObjectID; 


void TSmartPointer: :SetObjectID(ObjectID objID) 
{ 
fObjectID = objID;: 
if ((fRealObject ! 
{ 


t->GetObjectID () 


OpusBug ("setob 
} 


TPersistent “-PersistentCont 
if (fRealOb: 


if (aContext != NIL) 
retval = aContext; 
} 


return retval; 
etPersistent xt (TPersist 


‘RealObject->GetPersis 


OpusBug ("SetPersistentContext inconsistency") ; 


} 


MCollectible* TSmartPointer: :GetRealObject () 
{ 
MCollectible* retval = fRealObject; 


if ((retval == NIL) && (fPersistentContext != NIL)) 
{ 
retval = fPersistentContext->Retrieve (fObjectID) ; 
fRealObject = retval; 
} 
return retval; 


y 
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void TSmartPointer: :SetRealObject (MCollectible* realObject) 


{ * 


fRealObject = realObject; 
if (fRealObject != NIL) 


{ 


fPersistentContext = fRealObject->GetPersistentContext (); 
fObjectID = fRealObject-—>GetObjectID(); 


} 


Now, if TArnKey is declared like: 
class TArnKey : public MCollectible, public MEternal { 


public: 


@ Registered /Restricted 


t, MCollectible* nextOne=N 


rator>>=(TStreamé) ; 
rator<<=(TStream 
qual(const MCol 
Hash () ; : 
const TTexté& GetText (); 
re virtual functions... 
Macro (TArnKey) ; 


667) 


eed 
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Why do the cheetah classes look the way they do? 


There are a number of goals associated with the interface to developers for cheetah capabilities. I shall 
present them here in no particular order: 

1. Developers should have to write as little boiler plate code as possible (none would be the ideal case). With 
proper development system support, all of the boiler plate code could be automatically gencrated 
for any of the schemes presented; however, we can not count on this kind of support. Furthermore, 
the best the development system could provide is a default solution which would be 
reimplemented in all but the simplest classes. 

2. The interface presented should not add any appreciable overhead to the overall execution of cheetah. Any 
interface chosen should not require a significant amount of speed or space overhead to the 
flattening or expansion of an object. What represents a significant amount of space or speed 
overhead is certainly open for interpretation. 

3. Semantically different operations on the same class or type should look significantly different. cheetah 
provides support for flattening and restoring objects of known type as well as flattening and 

restoring objects of potentially unknown type. some believe that flattening an object of 1 unknown 


people but make someé'péop! 
(80% ?) people feel comfortable 
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The Ideal Solution 


The ideal solution would satisfy the goals above. Ignoring whether or not this solution could be 
implemented in C++, the code to flatten a group of objects might look something like: 


{ 


TToken aToken; 

TPoint aPoint; 

long aLong; 

char aChar; 

MResponder* aResponder; : 
// stuff // 


TMemoryStream aStream; 
FlattenObject aTo 
FlattenObject aLo 
FlattenObject aCk 
FlattenPointer 


} 


tual implementation of the “flatten” meth 
xpanding a group of objects: 


For now, we'll ignore t 


articular class or type. 
Let’s look at the code f 


// assume aSt 2, with a flatte 


TToken 
TPoint 

long 

char 
MResponder* 


aChar (aStres 
aResponder = Un: 


} 


MResponder), 
appropriate con 


Without going int 
expand methods are constructors), this solution certainly satisfies the goal of being somewhat nice to look 
at. Semantically different operations are distinguishable (FlattenObject vs. FlattenPointer), and 
semantically similar operations on different types are performed in the same way. Since I certainly can’t 
implement this in any known language, we can’t make any claims about whether this interface adds any 
overhead to the flattening and unflattening process. It certainly doesn’t have to. The flatten and expand 
methods could be made symmetrical in my mythical language and the developer doesn’t have to write 
any boiler plate code. 


Unfortunately, we can’t come close to this in C++; however, this so-called “ideal” solution illustrates a 
number of important features of a good solution in C++: 
1. The same operator is used to flatten an object of any type to a stream. 
2. A different operator is used when flattening pointers to objects of unknown type. 
3. Constructors are used when expanding objects of any type from a stream. 
4. The syntax is such that the flattening of pa objects to a stream could be written as a single 
statement if that is desired. 
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Bjarne’s Rules of the Game 


Before examining the solution space, here is some information about C++ that is absolutely necessary to 
know when designing a solution to this problem. Reader: I assume-that you know C++ already; 
however, I will point out a number of subtle and not so subtle “features” that are extremely important 
when designing a solution (After each point, say to yourself, “Thank-you Barney” and bang a large mallet 
against your head.): 

1. C++ provides for constructors of objects only. Built-in types do not have to be initialized and there 
is no syntax that looks like a constructor for initializing built-in types in any event. 

2. The operator overloading mechanism in C++ allows binary operations to be overloaded as either 
member functions taking one argument (the “this” pointer is the first argument) or as a global 
functions taking two arguments. This is the only mechanism available which allows an expression 
to be written involving built-in types and user defined types and have the expression look the same 
independent of the type of the object. An expression, (a >> b) will either execute the global 


function operator>>(A&, B&) or the member function A: :operator>>(B&). For built-ins, a 
global functions of two arguments is called. For classes, a member function is called. 
3. Constructors have ‘s like type-name (args...) 
not possible to ha ke an operator (Other lan 
to be considered a constructing the objec?) 


tly are. Furthermore, 
seclass you are pretending 
the gee is. T m classes A and B could be 
viewed as an / 
to the object v 
implementa: 
6. Ifaclass has base classe: 
the constructor for the deri : e sses 
are initialized in the order speci. 


members in the order specified by the: 


é Registered /Restricted Cheetah Thursday, March 1, 1990 2.1.3 - 18 


Let’s Make A Deal 


Now that we know the goals, the ideal solution and the limitations, we should be able to examine the 
alternative solutions. I will try to present alternatives in isolation; however, many choices affect other 
choices to be made later because C++ is not symmetrical. Let’s start with an apparently easy choice first: 
how to flatten objects. 


Flatten 


If we want semantically equivalent operations to be expressed identically, independent of the type of the 
operands, we are left with exactly one choice in C++ on how to do this. We must use operator 3 
overloading for flattening objects and built-in types. If we are willing to accept that objects are written to 
a stream one way and built-ins are written to a stream in a different way, the code for writing an object to 
a stream would be: 


anObject->Flatten(aStream) ; 


The code for flattening a bi 


or which takes a built- 
mentors can define a 
n argument. For the 
or>>>. We want to be 
sus a member function of a 
the type of the 


If we are not willing to : 
in type anda TStream 
member operator for a: 


purposes of our disc 
able to make this ove 
stream.‘ Therefore, : 
object would be so 


At this point, you’re thinki 
the catch? Well, of course, you mig 


myObjectOfType3 >>> myObjé 


I can live v at’s 


Actually, you can do this, provided two thing 
returna TStream&. Also, the overloaded ope 
restriction, you could still write the expressio you’ iS i ces as 
in: 

(myOb 4 ecti 


Forgetting a pare : 
numbering reflects ¢ object is actually written to the strea : 
decisions which we would like to make. First: Should we allow multiple obje ) be flattened using 
an expression which is written in a single statement? The obvious answer is yes; however, because 
we'd like to use constructors to expand objects, and constructors are clearly one per statement (and 
because of other reasons which will be explained later), this question is not so easy to answer. We can 


enforce the choice that is made by returning or not returning a TSt reamé as the result of the operation. 


The next question is: What operator should we overload for flattening? Unfortunately, we can’t answer 
this question until we answer the previous question because if we only allow a single object to be 
flattened per statement then operators which group right to left would not have the obvious advantage. 


3. This operator does not exist in C++ and therefore could not be used. We will reveal the choices for 
this operator shortly. 

4. If it was a member function of a stream, it would not be extensible in the same way. A global 
operator (which couldn’t be virtual and therefore wouldn’t work for our scheme anyway) would 
have to be defined to flatten your object. This operator would no doubt have to be a friend function 
so that it could touch your private parts. This is what Barney’s stream package does. It’s ugly. We’re 
not doing that. We have high standards. We’re Apple. 
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So, let’s assume the answer to the previous question and then try to answer this one. If the answer to the 
previous question is that we will not allow multiple flattens in a single statement, then basically any 
operator is fair game. We'd probably like to choose one that ee some directionality. Therefore our 
choices are the following: 

Pe PS, PP, 225, —>, Ie II 
I can quickly eliminate some of these choices. Using > or >= is unacceptable since they are already 
overloaded for MOrderableCollectible objects. Overloading -> is a very bad idea because it already 
has a useful meaning for many of the objects we are talking about. Overloading | or | | has the 
advantage that it resembles a Unix pipe and that is something that C++ programmers are familiar with. 
Overloading >> certainly has the best directionality; however, it might confuse C++ programmers who 
use Barney’s stream package since the functionality is similar but the syntax would be opposite of 
Barney’s. Overloading >>= has good directionality and it is rarely, if ever, legitimately used; however, it 
makes atleast one person in Pink violently retch to the point of not being able to think clearly because we 
are overloading one form of assignment. More importantly, we are overloading assignment in a way that 
is counter-intuitive since the thing being “assigned into” is on the right hand side rather than the left. 


If we want to allow multip 
right to left or we are force 


right to leftis >>=. All| 


“Ts eines an objet c 
an object of known 


(the actual object c 
flattening an object 


What should the name of the function to eas i 
member function e 


Expand 


At this point, you are thinking to your self, “Self, these choices weren’t so hard. In any event, it looks like 
things will be pretty clean.” Now it is time to start compromising. It is not possible (even if we wanted 
to) to make the “expand” operation look the same independent of what we are expanding for a number 
of reasons which will all be explained. 


Here is where we need to make our first hard choice. Ideally, one would like to view the process of 
expanding like a constructor. The argument to the constructor would be a stream. The constructor 
would then use the stream to build the object. Unfortunately, you cannot call virtual functions in a 
constructor. This is too great a restriction because some classes require that a virtual function be called to 
“add” objects to the class when expanding the class from the flattened form. Furthermore, there are no 
constructors for built-in types. 


5. When I say unknown type, I really don’t mean it. I mean it is definitely of type MCollectible; 
however, we don’t know which derived class it is. 
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Alternatively, we could provide a constructor which builds an empty, uninitialized object (much like an 
uninitialized built-in), and then call an expand function (in our case an operator so the expressions look 
the same). So the question is: “Constructors or operator<<< method?” The advantage of using an 
operator is that we could write code like: 
{ 

long aLong; 

TToken aToken; 

char aChar; 


aChar <<< aToken <<< aLong <<< aStream; 
} 


The disadvantage is that we need to provide a distinguished constructor or make the expand method 
smart enough to deal with an arbitrarily initialized object. (In my example, I’ve used the constructor 
with no arguments. We might not want to grab this one because of its legitimate uses.) Furthermore, it is 
less efficient because now w. structure twice. Once calling constru 
second time calling inherit tionally, the lack of forced initializat 
constructors (which is wha for built-in types is a disadva: 


¥ mechanism for readi types from a stream. 


oices. We could just overload the operator 
‘suggest that you should initialize your va 


If we use constructors, w 
There are basically two é 
programming style wo 
; 
long aLo 
aLong <<< a 


following statement. 


TToken aT 


char aChar; 
aChar <<< aStream; 


) for all the b 


in our things is 
{ 
long aLong 
TToken aToken 
char aChar = char(aStream) ; 
} 


As usual, there are two choices for how to read back unknown objects. We could provide an overloaded 
operator to read objects back in. However, in order to implement this, we would be forced to change the 
runtime of C++ to use a scheme which did not move the “this” pointer in an object.® I will assume that 
this is not practical. Therefore, the only choice is to provide some kind of function which performs the 
“new” of the object and calls the constructor. The user will have to write the cast back. Therefore, the 


code to bring back an MResponder* of unknown derived type would look like: 
MResponder* aResponder = (MResponder*) Resurrect (aStream); 


6. You’ll have to accept my word on this. Basically, the problem is that we need to do a cast back when 
reading in an object of unknown type (actually an MCollect ible*) if we want to store this object as 


anything other than an MCollectible*. The only way to write this cast back is to actually write it 
in the code as part of an assignment statement. If we changed the runtime, this cast back would be 
unnecessary. 
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What should the name of global function to “resurrect” an object be? When there are static member 
functions, this can be a static member of MCollectible. For now that is not possible (because you 


would need one MCollect ible object to resurrect another one). Because this is our only choice for 
expanding an object of unknown type (which many consider to be a semantically different operation than 
expanding an object of known type) and our desire for symmetry between flatten methods and expand 
methods, we should carefully examine our decision for how we want flattening unknown objects to look. 


Implementation of operator<<< and operator>>> 


. 


All user defined types which want to be flattened to a stream to be restored later must implement a 
operator<<< which takesa TStreamé& as an argument. Also, they need to implement operator>>> 


which also take TSt reamé& as an argument (and may also return this depending on whether we allow 
more than one flatten per statement). Classes which want to be flattened to streams via a pointer toa 


unknown type, must desce f | : 


. 


Let’s take a look at a few 
class TPoint { 
private: 
long £X; 
tong f£Y; 
public: 
TPoint (); 
...other 
TStreamé& 
TStreamé& 
...other 
}3 


TStream& TPoint::operator>>>(TStreamé& aStream) 
{ 


£X >>> aStream; 
£Y >>> aStream; 
return aStream; 


} 


This example illustrates that adding these methods to a class without a vtable does not force this class to 
have a vtable and thus adds no overhead to the size of the objects. Reading and writing points toa 
stream is trivial as in the following example: 
{ 

// Writing a point 

TPoint aPoint(100,200); 


7. This will make the operator>>> a virtual operator. Also, there is one other method which must be 
overridden (to supply the class name) but that is unimportant for our discussion. 
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aPoint >>> aStream; 


// Reading a point 
TPoint aPoint; 
aPoint <<< aStream; 


} 


Okay, let’s look at the implementation of the flatten and expand operations for a slightly more 
complicated class: 

// TView’s lineage is not entirely known; however, we do know that it 
// is an MCollectible object. This means that there are additional 
// methods that we need to implement but they are not important for 
// this example (the additional method is GetClassNameAsString. It 
// could easily be of * HOOPS.) 


class TScrolibar 


private: 
TPoint | f£ThumbP 

public: 
TScrollbar(); 


other con 
TStream& oper 
TStream& ope 
other m 

}; 


TStream& TScrollbar::operator 
{ 
TView: :operator<<<(aStream) ; 
fThumbPosition <<< aStream; 
return aStream; 


TStream& TSc; 
{ 
TView: :operat. 
£ThumbPosition >>> aStream; 
return aStream; 


} 


Now flattening and expanding TScrollbar objects looks identical to all of the other examples. Note 
that the order that objects are flattened should follow the order that they are expanded. 


Writing or reading an object that is known to be a TScrollbar but could be a subclass of TScrollbar 
is accomplished with the following: 
{ 
// Write out a TScrollbar* 
TScrollbar* foo; 
got foo from somewhere. 
FlattenPointer(foo, aStream); 


@ Registered /Restricted Cheetah Thursday, March 1, 1990 223 


// Read in a TScrollbar 
TScrollbar* aScrollBar = (TScrollbar*) Resurrect (aStream) ; 


As a final example, let’s examine a somewhat complicated class: 
class MResponder: public MCollectible, public MCollectible { 


private: 
TToken finstanceName; 
MResponder* fSuperTarget; 
protected: 


MResponder(); 
-- more constructors 
public: 
TStream& operator<<<(TStreamé&) ; 
TStream& operator>>>(TStream&) ; 
}; 


TStream& MResponder 
MCollectible::op 
fInstanceName << 
£SuperTarget = 
return aStream; 


Responder*) Resurrect (aStream) ; 


TStream& MResp 
{ 


MCollectible:: ox? 
fiInstanceName >>> aStream 
FlattenPointer (fSuperTarget, 
return aStream; 


Expanding an MResponder from a stream is ssible. Exp i : ma 
stream or “resur. 1 MResponder from 
protected. 


Conclusion 


C++ is an ugly language. The design of the operating system of the 90’s is being driven by a short, 
balding, Scandinavian dude currently residing in New Jersey and working for the the phone company. 


I really want to know what you think about what was presented here or maybe you have another scheme 
entirely. In any event, my current mode of thinking is to make the following choices: 

1. Allow multiple flattens in a single statement; however, discourage its use when writing flatten 
methods because if you write your own flatten methods like this then it looks less symmetric with 
the constructor. I’ve waffled on this a bit; however, I think it is legitimate to want to write multiple 
flattens in a single statement when flattening objects in the rest of your code. It’s quite possible that 
symmetry is impossible in these cases anyway since another module, program, etc. could be the one 
reading it back in. In that case, you might provide a specification of the format rather than an 
actual piece of code. I don’t know. I still need your help. 

2. Since I’m still waffling on number one, I’m still waffling on the operator to use. I have to admit, I’m 


favoring operator>>= and operator<<= even though it makes one person violently ill. I don’t 
really like any of the other choices. I’m down on using >> because of its current meaning in C++ 
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which is too close to how we want to use it. 
. Use expand methods because you can’t call virtual functions in constructors. 


. Encourage the use of FlattenPointer which will be a static member function eventually. 
5. The name of the function to bring back an object is Resurrect. 


fe OO 
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Introduction 


Credence! provides concurrency control and recovery (commonly called CCR) for the Pink 
environment. Concurrency control handles the problem of multiple tasks accessing data at the 
same time by making it appear, at least to your task, as if no sharing is occurring. Recovery 
addresses the problem of failures that leave data in an inconsistent state by making it appear 
that failures never occur. Failures, in this paper, include program, power and system failures 
but do not include media failures. Most existing CCR software have been components of specific 
programs, e.g. a DBMS, for which the CCR design has been tailored. Credence is a set of classes 
and protocols that offers-CCR functionality for the extensible data types possible in the Pink 
world. 


sam or in 
data. You need 
= Concurrency 
fesigner to use 
seful enough to 


han one task , either in 
t least one task is chan 


You need concurre! 
different teams, acc 
recovery if you wis 
control and recov 
Credence proper! 


You need concurrency control when dat 
complications caused ae. reentrancy ina 


concurren &.Serl i I i $ D sible 


execution. 
serializable. 
while resulting it in mor 


The most common techniques for concurrency control involve acquiring and releasing locks of 
some type. A lock is an abstraction such that when you acquire (or set) it, you have access to 
some associated object and prevent others from accessing the object until you release the lock. A 
task, which is requesting a lock, is blocked until the task gets the lock. Locks usually have a 
type, e.g. read and write locks, that reflects which operation you are about.to do. Depending on 
the type of the lock, multiple users may be able to concurrently acquire a lock and still preserve 
serializability. 


Although the etymology is obvious, convention was elected over Mr. Fogerty’s iconoclastic 
spelling. 
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Serializability and locks have their limitations. - For some applications, serializability may 
not be desired. The syntactic notion of holding locks also may be too restrictive. For instance, an 
operation that balances a tree does not change the semantic content of the tree but a lock ona 
node or branch of the tree might prevent the tree balancing operation. 


You might still be asking, “But what’s the difference between locks and semaphores?” 
Actually, locks are very similar to sharing semaphores but provide the extra baggage to relvase 
locks in a manner that guarantees recoverability and to handle deadlocks. 


Recovery : 


Failures can can cause logical inconsistencies in data. These inconsistencies can result when two 
or more data items, all dependent on each other in some way, must be written to disk but the 
disk hardware can not write all items in one fell swoop. Recovery is a guarantee that failures 
don’t result in data inc 


Transactions 


A transaction is a use 
transaction isa 5s 


cy control. A 


is consistent, which mea r succeeds and 


ts.and has no effect. 


['ll abbreviate the consistent a¥ by saying % 


transaction is atomic.2 


In terms of what I’ve already presented 
serial relative to the operations of some 6 
updates that must all succeed. 


¥ control as seen in the definition of 


¢ A transaction T1 is said to read from transaction T2 if T2 writes some x 
which is later read by T1. 

¢ A transaction T1 is recoverable iff Tl commits after every transaction from 
which T1 read has committed. 


2My definition of atomic differs slightly from that in most database CCR literature which also 
includes serializability as a condition for atomicity. 
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The requirement that a transaction commits after every transaction from which it has read is 
sufficient for recoverability but can lead to cascading aborts. We can make our implementation 
of recovery easier: by requiring: 1) that a transaction only reads from committed transactions; 
and 2) that a transaction can only write x after every transaction that previously wrote x has 
committed. The first requirement avoids cascading aborts and the second allows before images 
to be used in the log. An execution that meets these two additional requirements is said to be 
strict. 


Two-Phase Locking 


Two-Phase Locking (2PL) is a protocol for using locks that provides serializable concurrency 
control and guarantees strictness. The 2PL protocol involves acquiring and releasing locks in two 
phases: locks are acquired during the course of a transaction (the first phase) and released, all 
at once, at the end of the transaction (the second phase). 


Logical Locks 


In the database wo 3 ords. How can 
we use locks with 


lock is, basically, : 


The use of logic 
data items by us 
indicate a lock 


A transaction system is distributed if a 
in a network. Distributed transaction syst 


might act differently for local files than for files on Appleshare volumes. For instance, we 
expect the Pink file system server to work with the transaction system so that a file system 
request made from within a transaction, for instance, truncating a file, would only truly truncate 
the file when the transaction commits. This might not be possible with network files. 


Architecture 


Credence provides classes that provide transactions, recovery, and concurrency control. Classes 
are available to create transactions, change files in a recoverable manner, and request 2F is 
locks. Moreover, Credence provides a framework for recovery and concurrency control that 
allows users to modify the default mechanisms without starting from scratch. 
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Transactions 


Credence provides a class (TTransaction) that allows you to start and end transactions within a 
task. There is, at most, one transaction for a task and the transaction is only active for the task 
that started it. Methods are available to commit transactions, abort transactions, and find 
which transaction, if any, is currently active for the task. 


The definition of a transaction involves control flow because, when a transaction aborts, you 
typically don’t want to perform the remaining operations in the transaction. For this reason,. 
the transaction class uses C++ exceptions to alter the control flow when a transaction aborts and 
defines a protocol for handling these exceptions. 


Concurrency C 


Credence concurreng 
requests for the loca 
locking based on | 
Manager and your 
never explicitly 
the transaction. : 


é re 2PL locks, you 
‘the termination of 


The type of alock i ; ot ill bi : Aicts 
with an existing lock. * : 


conflict with write locks; write locks 
specifier so that a lock on one file does ni 
file. For example, placing lock 0x100 for 
“Blue”.The file specifier is used to iden 


Because of the overhead involved, you should not use locks when semaphores will do. 


Recovery 


Credence provides classes that let you easily access files in a recoverable manner. One concrete 
class (TSafeFileSegment) exists that allows you to use memory-mapped files in a normal 
fashion and makes changes recoverable with a minimum amount of work. Another conercte 
class (TSafeServer) provides a recoverable stream interface to a file that is handled by a 
separate team, a data server. You use a data server when you want to share the file between 
more than one team, or you don’t want to map the file into your address space, or the file is 
larger than a team’s address space (because the data server will use a pool of buffers to access 
the file). 
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Credence recovery uses write-ahead logging in which all changes to recoverable objects are first 
written in a central, system log. The Credence system provides the facility for recording 
changes into the system log and playing back the lock in the event that a transaction aborts ora 
system failure occurs. The default type of logging is called physical logging because images of 
which bytes changed are saved in the log. Credence Recovery is based on two abstract classes: 
MRecoverable and TLogRecord. 


Any object that is considered recoverable (a disk file) must be an MRecoverable. Any changes to 
an MRecoverable results in a log record. The MRecoverable class has a method that outputs the 
log record to the log file which must be overridden, thus allowing a subclass to do its own : 
logging. MRecoverable hooks itself into the transaction system so that the transaction system 
can notify it of events. MRecoverable has methods that are called when transactions start, 
commit, and abort since this information is needed if the class is doing its own logging and can 


what algorithms a 
while other schem 
images, or both. 


sed for logging: For instance, some logging $ 
se physical log records; some log records. 
- records are created by instantiating objects 


The transactiona 


methods could redo or undo the chang; 
the system. 


TSystemLogRecord is a subclass of TLogk 
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Figure I sh 
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thie Credence system anc 
t@ classes that send these més 


3The names of these recovery schemes come from whether you need to undo changes by aborted 
transactions or redo changes made by committed transactions in order to recover. 


a a a 
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« Registered / Restricted Credence Classes March 15, 1990 2.1.4-8 


Class Diagram 


You don't need to know these classes unless you want 


custom locking or recovery 


TTransaction 


TSurrogate 


TSafeFileSegment 


TSafeServer 
TNRLogRecord 
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Classes and Methods 


TTransaction 


A transaction is started by the definition of a TTransaction object. The most important methods 
that you will use are the following: 


¢ TTransaction — the constructor starts the transaction 

¢ Commit — commits the transaction. 

e Abort — aborts the transaction. 

¢ GetActiveTransaction - returns a pointer for the TTransaction active for the 
current task. 


An exception is raised 
should be prepared 
Andy’s exceptions ¢ 
transaction along 


“For this reason, code that in 
re have real C++ exceptions; 
owing code illustrates.cf 


an 


d committing a 


foo () 
{ 


EXCEPT = 
// put code héeré 
ENDTRY 


You commit a transaction by calling Com 
transaction if Commit hasn’t been called. 
Abort. : 


Only one 
TTransact 
whether a transa 
find out. 


dy active will raise a 


active entering a function, you can tu: insaction to 


A Preview of Exceptions 


The design of C++ exceptions still hasn't stabilized but the Credence classes will use something 
similar to the following (based on Stroustrup's design at the time | wrote this paper). 


There will probably be at least one class, TTransactionException, of which an instance is uscd to 
signal an exception associated with transaction errors. The following example shows how you 
would use transactions with exceptions. 


foo{) 
{ 


TTransaction t; 
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// transactional operations 


t.Commit (); 
} 


catch( TTransactionException p ) 


{ 


// put code here to execute if the transaction aborts 


} 


TSafeFileSegment 


The TSafeFileSegment class is used much like a TFileSegment except that changes are atomic. 
You can access a TSafeFi ‘ough streaming operations. Any dire 
must be bracketed by id ChangesDone. Any block of COR 

operations that write: TY 


2 0 bytes within a memory-mapped file> 
TSafeFilé nt..myFile (filePtr); // filePtr 
40. tination, 100); : 


X >>= “AVE Les 
y >>= myFile; 
z >>= myfile; 
myFile.ChangesDone (); 


more than of 


Executions defined y ChangingContents ( or ChangingStream) and Changes pairs must be 
disjoint, i.e. a ChangingContents (ChangingStream) must be followed by a ChangesDone before 
you can invoke another ChangingContents (ChangingStream). 


TSafeServer 


The TSafeServer allows you to access a file atomically through a data server. You can use the 
TSafeServer class when you need to share a recoverable object between teams or you don’t want 
to map a file into your application’s address space. The methods of this class will send read 
and write requests to a data server. All access to the file is via TStream operations. You use the 
ChangingStream and ChangesDone functions in the same way as for TSafeFileSegment. The 
server team is launched if one doesn’t already exist for the file. The server team will use a pool 
of segments to access the file instead of mapping the file completely into the server’s address 
space if the file is larger than a team’s address space. 
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The data server does not automatically perform concurrency control. However, you can use 
TLogicalLock to control concurrent access to a data server. De-coupling locking from data servers 
allows greater flexibility in locking while allowing simpler data servers. 


Note. [ could design a couple more types of servers if demand warrants. For instance, a server 
that only handles write requests because the clients have a read-only, shared segment in their 
own address space. 


TLock and TLogicalLock 


The TLock class is an abstract class that provides the framework for lock-based concurrency 
control. The most useful methods of this class are as follows: 


° ee Lor ~ set cs actus the lock. 


A0gical locks. 
value, and type. 
l ock or can be 

in the following 


The TLogicalLock 
As mentioned earli 
These component 
accessed with get 
code: : 


ed from TLock that provid 
riponents: a file spec 
: #t5'to the constructor of the 
and setter r functions. The use of a logical le 


TSurrogateTransaction 


When a TTransaction is instantiated, the object is associated with the task that is running and 
communication is set up to the Transaction Manager if such communication hasn’t been 
established already. The Credence teams, Logger and Lock Manager, deal with these 
transactions but don’t want to do the actions mentioned above each time they resurrect a 
transaction object. The TSurrogateTransaction class is used for this reason to provide surrogates 
for transactions. 


SESE 
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TLockController and TLogicalLockController 


When a TLock is set, it actually sends a request to the global Lock Manger team. The Lock 
Manager determines which subclass of TLockController is needed to control requests for the lock 
being requested and instantiates a TLockController if one doesn’t already exist. 
TLogicalLockController is, naturally, the subclass that handles TLogicalLock requests. 


MRecoverable and MSystemRecoverable 


As mentioned earlier, MRecoverable is a class that you must mix into any object to which you 
want to apply recoverable changes. It has the knowledge to hook into the transaction system so 
that it can find out about transaction events. You can obtain complete control over logging by 
deriving from MReco 
MSystemRecoverable: 
logging process. 


The abstract MRecos “has now been 


ord that includes 


not write changes made by unco 
safely on disk. For instance, if the vir 
changed by a transaction that hasn’t yet 
records are written to disk first. The Forcé 
to disk. 


TLogRecord is the perclass of all log records. If an MRecove ethod changes an 
MRecoverable, the method is responsible for instantiating the right kind of TLogRecord for the 
logging scheme in use for that MRecoverable. The only methods of TLogRecord are as follows: 


¢ Undo - undo the changes represented in this log record. 
¢« Redo — redo the changes represented in this log record. 


TSystemLogRecord is an abstract class that includes enough information in the log record to 
work with the system log. 
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TURLogRecord and TNRLogRecord 


The TURLogRecord and TNRLogRecord classes are concrete subclasses of TSystemLogRecord 
that support undo/redo and no-undo/redo recovery, respectively. These are used within the 
transaction/logging system to implement TSafeFileSegment and TSafeServer. 


More Things You Need to Know 


Classes that use locks must be good citizens. You must make sure that all classes accessing 
shared data use a common locking scheme. You can use locks in concurrent tasks in a team to 
access data in memory. You also use locks by multiple teams to control access to data ina 
TSafeServer. 


Anyone using MSystern that the executions are strict. Exe 


strict if one of the foll 


hedatats ‘not uséd* concurrently, i.e. access i 
ou use the concurrency control of TLogicalL, 
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Examples 


The first example shows how the locking would work for classic database concurrency control. 


// Set lock for record “fred” in the file “My File” 

ie 

foo(const TFile& file) 

{ e 
// first, create a lock object (doesn’t set it yet) 
TLogicalLock myLock (file, 0, kWriteLock) ; 


// Use a data base index object capable of mapping a key to a 
// vecord ID value. The record ID will be used as the lock 

// value in the..logical...lock. 
long value =. 


set the lock 
-SetLock () ; // This may b] he lock can be set 


} 
// 
const long kWholeFile 


f(const TFile 


kWr 


kWholeFile, 


EXCEPT 
error(“transaction aborted unexpectedly!”) ; 
ENDTRY 


The next example shows a member function of some random class that writes to a 
TSafeFileSegment. 


TRandomClass: :WriteRecoverably (TSafeFileSegment& stream) 
{ - 


TTransaction t; 
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stream.ChangingSt ream() ; 
fFoo >>= stream; 

fBaz >>= stream; 
stream.ChangesDone (); 
t.Commit (}; 


gprintf (“transaction was aborted\n”); 


The next example shows writing to a TSafeServer. (Notice that the operations are identical to 
the stream operations using a TSafeFileSegment.) 


TRandomClass: :Serv: lerver’& server) 


sborted\n”) 


The following example aborts the curré 


TT TTransaction: :Get 


ift 


saction { 


->Abort (); 


EXCEPT 
qprintf(“yes, it did abort\n”); 
ENDTRY 


é Registered / Restricted Credence Classes March 15, 1990 2.1.4-16 


_Rainbow. Warrior 


Preliminary ERS Apple Confidential Thursday, March 1, 1990 Page 1 


“read 


d the 


ith the Blue resot 


wo & 
State 
Om & 
Oe 
on 
Les 
2ee 
Seo 
mR . 
56 


cea 
ex © 
CY 
ee 
BB 
a6 6. 
vat 
Em PO 


2.1.5 - ii 


Thursday, March 1, 1990 


Rainbow Warrior 


#@ Registered/Restricted 


Introduction 


The purpose of Rainbow Warrior is to provide an “environment variable” registry and notification 
system under Pink. The combination of Rainbow Warrior and the “read-only” resource fork provides a 
superset of the services available with the Blue resource manager. 


Rainbow Warrior provides facilities for accessing and updating environment variables (both system 
environment variables and local environment variables). It also provides facilities for receiving 
notification when a change is made to an individual variable or a change is made to any variable 
belonging to a particular category. For example, applications using this facility can be notified when new 
fonts are installed in the system or additional shared libraries are available. Rainbow Warrior provides a 
stack of environment variables “environments” so applications can shadow variables declared in the 
global environment with their own definitions. Finally, clients can enumerate all of the environment 
variables or all of the environment variables in a particular category. 


A mechanism for pre-change notification and “voting” for a change to be allowed is being consi 


NOTE: This is a very preli #nhe Classes 


that a client would use. 


imple provided and “hea 


Example 


jf a TApplication is 
There is also 
my te 4 


// For the purpo 
// GetEnvironme 
// a call in TA 


this..example, assume that 
@turns the current 


TEnvironment Sta 
TEnvironment* applica 


// applicationEnvironment is alx¢ 


// Query for a particular shared 1 
TToken category (“SharedLibrary”) ; 

TToken instan SpecialTextClasse 
TSharedLibra: (TSharedLibr 


environment —->R 


// Test for the 
Boolean exists = 


‘a particular shared libra¥r 
ent->Member (category, instance); 


// Check for the user name 
TToken userNameCategory (“User Name”) ; 


// The returned TToken object belongs to you. 
TText* userName = (TText*) environment~>Retrieve (userNameCategory) ; 


// Add an environment variable to the “application environment.” This shadows 
// any definition of the same environment variable found in another 

// “TEnvironment” further in the “environment stack.” Note that there are 

// atleast two other “environments” below the “application environment” in the 
// environment stack: the “user environment” and the “system environment.” 
TToken userShoeSize(“Shoe Size”); 

TCollectibleLong shoeSize(9); 

applicationEnvironment->Add(userShoeSize, &shoeSize); 
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// Add an environment variable that is has a category and instance name 
TToken category (“SharedLibrary”) ; 

TToken instance (“MySharedLibrary”) ; 

TSharedLibrary* lib = new TSharedLibrary(....); 
applicationEnvironment->Add(category, instance, lib); 


// Get an iterator to iterate over all of the sharedLibraries. 
TIterator* anIterator = environment->CreateIterator(“SharedLibrary”) ; 
TToken* nextLibrary = (TToken*) anIterator->First(); 
while (nextLibrary != NIL) 
{ 
// Do something - could retrieve the value associated with this, 
// ete. 
// The “nextLibrary” text object belongs to you 
delete nextLibrary - 
nextLibrary = (TT xt (); 


// Request notification: wheneve éharige is made to 
// shared librari 
// Assume you hav: 
TMessageTaskNoti 


tion.notification (aMsgTask, 
environment ->Not dtd 


1)? 


Classes 
TEnvironment 


TEnvironment provides an environment vari 
provides methods for adding, updating, remo 
the set of environment variables are persistent a 
notified whenever.any:kind of change is made t 
or a category of : 
for the life time 


Applications will typic 
as the functionality of a TEn 
objects and should be managed by the caller. 


class TEnvironment : public MCollectible { 
public: 

TEnvironment (char* fileName?) ; 

TEnvironment (); 

virtual ~TEnvironment (); ¥ 

virtual Boolean Add(const TToken& category, 
const TTokené instance, 
const MCollectible* value, 
Boolean replace = TRUE, 
const TToken* replaceDetails); | 

virtual Boolean Add(const TToken& category, 


1. Of course, we will be using whatever class the file system provides for representing a file. 
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const’ MCollectible* value, 

Boolean replace = TRUE, 

const TToken* replaceDetails) ; 
Remove (const TToken& category, 

const TToken& instance) ; 
Remove (const TToken& category) ; 
Retrieve (const TToken& category) const; 
Retrieve(const TToken& category, 

const TToken& instance) const; 
Member (const TToken& category) const; 
Member(const TToken& category, 

const TToken& instance) const; 
Members (const TToken& category, 

TCollection& result) const; 
Notre yon (const TNotificationSpecifications) ; 
vonst TNotificationSpecifi 
itor() const; 
rator(const TToken& 


virtual void 


virtual void 
virtual MCollectible* 
virtual MCollectible* 


virtual Boolean 
virtual Boolean 
virtual Boolean 
virtual void 
virtual void 


virtual Titer 
virtual TIte¢ 


TEnvironmentStac 


A TEnvironmentSt vironments. Accessin 


TEnvironmentSta¢é e information i losest to 
the top of the stack. ig to access the the 
top most TEnviron tthe next en til the 


environment variable is found oral 
exports the interface for iterating ove 
when an environment variable changes, an 


class TEnvironmentStack 
public: 
TEnvironmentStack(); 
ticonment Stack ( 


public M 


: ‘cerator() co: 
ateIterator(const € 


virtual 


etrieve(const TToken& ca 

virtual MC Retrieve(const TToken& cate 

const TToken& instance) const; 
virtual Boolean Member (const TToken& category) const; 
virtual Boolean Member (const TToken& category, 

const TToken& instance) const; 
virtual void NotifyOn(const TNotificationSpecificationé&) ; 
virtual void NotifyOff(const TNotificationSpecification§&) ; 
virtual void Push (TEnvironment*) ; 
virtual const TEnvironment* Pop(); 
virtual const TEnvironment* Peek(); 
virtual TIterator* CreateEnvironmentIterator() -const; 
virtual void 
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StartHere (const TEnvironment*) const; 


Rainbow Warrior Thursday, March 1, 1990 2.1.5 -3 


TNotificationSpecification 


TNotificationSpecification is an abstract class that contains the protocol for describing when and _ 
how client receive notification when environment variables change. TNotif icationSpecification 
subclasses will override the Not ify methods to do the actual notification dispatching. For example, a 


subclass of TNotificationSpecification could supply notification using Opus IPC messages, post 
events to an event receiver task or send a packet on the network. 


The TNotificationSpecification encapsulates information which describes when notification will 
occur. You can request notification based on a particular category (all changes involving the category 
FONTS); a particular category and operation (all additions to the category FONTS); a particular category 
and instance (all changes involving FONT Helvetica13); ora particular category, instance and 
operation (whenever SHARED LIBRARY GoodStuff is updated). 


Synchronous notification é 
this will be considered 


class TNotificati 


public: 
enum NotaficationKind {kAdd, kRemove; 
kUpdate, kA 
virtual ionSpecification(); 
virtual : Notify (cong 
virtual 


virtual const TToken 
virtual const TToken* 
virtual NotificationKind 


protected: 
TNotifi: 


sonst TToken& cai 
const TToken& in 
NotificationKkKind yes 


TNot 
}e 


TMessageTaskNotification 


TMessageTaskNot ification is a notification specification which will perform notification by using an 
TNotificationMessage (a kind of MkKernelMessage) send to an MMessageTask. The 


TNotificationMessage can be queried to find out what category (and instance) changed as well as the 
nature of the change (update, addition or removal). 


class TMessageTaskNotification : public TNotificationSpecification { 
public: 
TMessageTaskNotification (const MMessageTask& who, 
const TTokené& category, 
const TToken& instance, 
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NotificationKind = kAll); 
TMessageTaskNotification(const MMessageTask& who, 
const TToken& category, 
const TToken& instance, 
NotificationKind = kAll); 
virtual TMessageTaskNotification(); 


override void Notify(const TToken& category, 
NotificationKind kind); 
override void Notify(const TToken& category, 


const TToken& instance, : 
NotificationKind kind); 


TNotificationMessage 


TNotificationMessage t to an MMessageTask duri 


encapsulates the categor 


class TNotificati 


public: 
TNotificat "‘oken& instance, 
NotificationKind 
“eonst TToken* rep; 
TNotific : kAll, 
virtual 
virtual const Ts: 


virtual const TToke 
virtual NotificationKind 
virtual const TToken* 


}3 
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Introduction 


Pink will be the first operating system that fundamentally integrates features necessary for 
support of native languages worldwide. It starts with the character encoding, which supports 
scripts and symbols for all languages and typesetting requirements, and extends throughout the 
toolbox, even up to the development environment (which is traditionally only a 7-bit 
environment). 


Pink provides high-quality layout of text in any language; layout which satisfies the large 
majority of typographical requirements and can be extended to meet others. Pink also includes 
other crucial language-sensitive features: text comparison and searching, keyboard mappings, 
inline input (integrating ideographic text input), etc. It also provides country- or region-specific 
features such as time and number conversions, and calendar, time zone and daylight-savings 
support. 

This document describes ma 
traditionally been referred 
localization support). The 
in a separate chapter. This 


Most of these iscaeeble objects are table-d 
functions. These objects are a subset of the use 
documents, other user configurations, etc. Use 
install or remove calization objects.! A 
functional interface 
format details. 


Localization Ob 


For the purposes of localization, there are a number of relationships which can be organized 
into a hierarchy. A script is a writing system consisting of a number of symbols and conventions 
for associating them. Examples are Roman (Latin), Cyrillic, Greek, etc. 


Each script can be used to represent a number of natural languages (for localization purposes, 
wherever one natural language is written in two scripts we will refer to them as two different 
languages: one example is Serbian and Croatian, which are essentially the same language, but 
one is written with Cyrillic and the other with the Roman script). In some cases a script is only 
used by one language (Japanese), while in others it is used by scores (English, French, 
German,...). 


Each language has a number of regions in which the language is used, regions which have 
different localizations (these correspond to country-codes on the Mac). Examples are the U.S. 


Whenever installed objects are selected, changed, added or deleted, the toolbox will need 
to synchronize applications and servers. 
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and U.K., or French, French Canadian, French Belgian, French Swiss, etc. Generally our 
products are localized to a particular region when we ship them: sometimes applications can be 
localized to just a language, however, if the differences among the regions of a language are not 
present in the application. | 


A locale is a part of a region that shares common time and date characteristics: For example, 
California and Oregon are part of the same zone, while Arizona and New Mexico are not (even 
though they are in the same time zone, Arizona does not have the same daylight savings as 
New Mexico). Users will generally personalize their systems by configuring their system 
differently from the shipping system for their region. 


Human Interface 


The exact ways in which the human interface is expressed and the system configuration 
methods implemented is not yet well defined. Most of the international interface elements are 
not simply the result of isolated international. programming efforts, but rather require 
participation and integrati q 
and configuration issues ai 
to be present for world-w 


The localization objects § 


language (see Presentation I 
will have a number of names and icons. 
language (there are some exceptions: some 
calendars or time zones, and are counted as b 
specific to a language will generally be in the: 
appropriate to the oe 


The system can ma 
localization objex 
interfaces can 
a filter to see jus 


Presentation Languages 


Application programs are able to handle many different languages in documents 
simultaneously. In a word processing program, for example, the user can enter French and 
German words into the same document: with Pink Unicode text, this will be transparent for non- 
Roman scripts as well. 


However, besides the languages that the user has entered into a document, each application 
uses a particular language in the menus, dialogs and other user interface elements for 
presentation of information to the user. This is the language that the application is localized 
for, and which we will call the presentation language. 


One of the major advantages of the Macintosh was the ability for well-behaved applications 
to be localized into any number of languages, changing the interface text without recoding or 
even access to the source code. This localization. of the presentation language often involves 
changing the other interface elements: since the length and content of text strings varies 
dramatically, elements of dialogs and menus often need rearrangement. Programmers also make 
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use of routines such as ParamText, that allow localizers to arbitrarily change the order and 
context of items in dynamically composed strings. 


On the Blue Macintosh, there is only one presentation language for an application and for the 
system as a whole (e.g. system messages, the Finder presentation language, desk accessories, 
control panel modules, etc.) Applications can change their own presentation languages (and a 
few do), but there is no system support and no uniformity in interface for doing this. 


The ability to change presentation languages is important for two reasons. First, allowing 
applications and the system to have multiple presentation languages allows both us and our 
developers to ship one product within a range of different countries, just as the same manual can 
contain several different languages for use in several different countries. Secondly, in many 
markets there is a requirement (in some cases governmental) for different people having 
different native languages to be able use the same product. These reasons are especially 
important in Europe, where the language support issues are crucial. 


Users must be able to selec 
that eventual interface is: | 
should be notified when tk 
languages if possible. On 
installation time, we allo 
appeared on the screen 
do not understand). Th: 
choice being in the res 
supported language a 


Note that actually thi 
are not sensitive to fF 
presentation coveri 
application may just switch toa: 
version (its text-to-speech could als¢ 


pak cane in a simple fashion Sa 


: Sieben in a number off eS 

entation language (bef 
‘that they are not faced with confusing me! 
an do this by selecting among different 
ive language). Applications will also ha 


The development system will need provid 
general. For example, the International Softwé 
things that make the translation process easi 
terms that should be used for consistency whe 


wound and glue. 1 
environment. For 


#24 in the French 2.0 versi sing , the 1.0 French version. In addition, the ability to annotate 
strings with explanations that are not visible to the user, but can be seen by localizers will be 
extremely helpful. 


For multiple languages within the same program, the development environment should also 
make sure that the translations stay in syne: if I add a string in the English version, then some 
string needs to be added to the French, and the localizers need to be able to find out what it is. 


TLocale 


Access to the international objects is through the Rainbow Warrior environments mechanism. 
By using this, for example, a programmer can iterate through all of the keyboards available on 
the system, or iterate through all of the number formats. One of the accessable objects is a 
TLocale. Each TLocale contains a set of international objects that are associated with a 
particular region (e.g. “Britain”, “US”, “Schwytz”, “Paris”, “Texas”). 


The TLocale mechanism allows users to change between different sets of international 
configurations with one choice. It also allows a set of objects to be packaged as one entity for 
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installation: adding Japanese to a system can add one or more Japanese TLocales, including the 
necessary keyboards, input methods, calendars, fonts, et cetera. 


For each language there is a preferred TLocale. This allows programs to determine a choice of 
items such as spelling checker based on language. For circumstances where no language or 
TLocale has been chosen, there is always a system default TLocale. A style-run of text that has 
no associated language is assumed to be in the language of the system TLocale, for example. 


Methods are provided for creating a new TLocale, iterating through the objects in a TLocale, 
changing the preferred TLocale for a language, and for changing the contents of a TLocale (e.g. 
changing the “American” keyboard mapping from “Querty” to “Dvorak”). The capabilities 
provided by these methods will be provided to users by a view. 


To use each of the international objects, applications will commonly access the system TLocale 
through Rainbow Warrior. They will then select the particular type of international object 


that they require: keyboard,.collation,.number. format, calendar, etc. 


Input 


Input of characters use 
the fundamental conve 
support and phonetic ¢ 
(eg. the 10-40 thousa 


Note that all of these 
example, for a sequen 
The keyboard will 1 
sequence or many § 
pick a “simple” one, with | 
the answer will indicate so, and invert 
by transliterators and input methods: aské 
string containing a set of characters that wi 


and input methods. are used for 


n of palate to characters; transliterat 


Keyboards 


A KeyMap con : 
KeyMaps may 
consists of zero 6 
inline input. Users can: 
keycode mappings. 


Note: transliteraters will be used to provide the functionality of “dead keys” on the Macintosh. 


There is also a mapping between the hardward codes emitted from the hardware and the 
so-called virtual keycodes. To see a discussion of this, consult the Toolbox. 
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HW Id Key Code 


Keyboard 
Server 


HW Id Key Code Modifier Set 


Transformer 


There may be multiple keyboard.m. a ith a given piece of 
hardware (one of th 
are common across ; 5 

mappings (e.g. te Is yard it 1a 
attach to which key: 


The system TLocale’s keyboard is used by default on the shipping system. Note that from the 
Mac hardware we can determine the type of keyboards connected (standard, extended, ISO, 
etc.) but we cannot determine the configuration of letters used on the keycaps (English, French, 
German), so users have to select the default keyboard mappings manually. 


According to the current ToolBox model, the choice of modifier keys is fixed, and limited to the 
current Mac set of 8 modifiers: shift, option, command, caps-lock, control, right-shift, right- 
option, right-command: we expect this to change to at least 16 modifiers. 


There is undoubtedly a good reason the hardware folks had for this; we are probably 
saving hundreds of cents per keyboard by not having different hardward ids for different 
keycap plastics. 
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The user interface for choosing keyboards and displaying them is not yet well defined. Two 
points are clear: there should be visible feedback as to the current keyboard, and there must be 
a fast “power-key” method of choosing keyboards (in addition to a Control-Panel style 
interface), since in many cases keyboards are switched very often. The keycaps-equivalent 
should allow type-through, so that the user can type (or click) characters on the keycaps 
keyboard and have the characters pass through to the next layer. Keyboards must also be 
switched synchronously: on the Mac the keyboard switching can lag behind key input, so that 
keys are mapped incorrectly. 


Creating and Modifying a Keyboard Mapping 

To create a KeyMap, the programmer specifies a default language. He then adds mappings to a 

KeyMap by successively specifying the following: 
a) a virtual keycode 
b) the modifiers that m 
c) the modifiers that 


d) (optionally) ah 
e) a result 
The keyboard id is opti 


keyboards (so that w 
either a single charac 


When an application or a keyboard server sup 
or more characters. Since an item of type TStyle 
of various lengths, fonts, styles, etc. (The Toolb: 
to virtual keys, ai 
There are two 
key downs (on thi 
patches out KeyTra 


Secondly, command keys will be treated differently. On the Mac, command keys are not 
sensitive to shift, but are sensitive to caps-lock: just the reverse of what should be done. The 
menu manager also up-shifts and strips diacriticals when matching command-keys, eliminating 
the possibility of distinguishing between # a, ¢8 A and 3 A. We will let application and 
menu manager easily determine what a key would have been without particular modifiers, so 
that it can determine that the user hit 444 \= Q (Command-shift-option-Q), without having 
to know that it happens to be # C on the current keyboard. 


Command keys also use a different mapping on the Mac than non-command keys; but this is only 
so that there are no command-dead-key combinations. This difference is not necessary in Pink. 
In addition, command keys need to be relatively constant: it would be very disturbing for users to 
have them change depending on the current keyboard (e.g. if | have a dingbats keyboard, I do 
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not want to get ¢ @ instead of ¢ A). To support this, users will be able to select their command 
keyboard separately from their current keyboard. 4 


The text classes will allow users to associate keyboards with fonts or styles, so that they can be 
automatically switched if the user desires. That is, when I click down in some Symbol text, I 
would like to automatically get the symbol keyboard, when I click down in some Russian text, I 
would like to get a Russian keyboard, etc. We will provide utilities for use by the text classes 
and applications to find a keyboard that contains a given character so that this can be done. 


Viewing/Editing A Keyboard 


There will be the equivalent of the keycaps desk accessory to allow users to view the current 
keyboard. Multiple keycaps can be open at the same time. A check box will allow the keyboard 
to type through to the next frontmost window. 


In addition, an extra command/ button will all w the keys to be edited. The editing paradigm 
will be that a key can be set: by pasting, inserting, order 


OEEe fagging text onto the key positio 
will ship keyboards that C 
fonts we ship with the syste 


aphic) characters represented 
another. 


A side panel or desktop: 
dragged onto keycaps. 
can be used: 


ons of this list 


b) Standard sot 
c) Ordered b 


by (a) or (b). — 


d) Customizable order. 


hg: mathema 


Keyboard Transliteraters 


On the Macintosh, dead keys are used to exten 
characters. With this mechanism, a user can ty. 
the keyboard int state, but does not 
indication of wh ’ 

with the accent—t 
produces 6). 


Dead-Key Example: 


Key Deadkey state Display 
b <none> b 
option-u <umlaut> b 

a <none> ba 

d <none> bad 


Certain command-keys will need to be reserved for the use of keyboard switching, input 
methods and transliterations. Since these keys are very frequent when entering text, they 


need to be easily accessable. On the Mac, we use various combinations of d6-space with 
other modifier combinations 4» No anda. 
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In Pink, this modal mechanism is replaced by the use of transliteraters. When the application 
inserts characters from a keyboard into some text, then it will call the list of transliteraters 
associated with that keyboard (and then the input method for the keyboard—see below). An 
accent transliterater can provide the same functionality as dead keys, in the following way. 
When the user types an accent, for example, the keyboard will generate a spacing accent,which 
is entered into the text stream. When the user next types a base character, then it is entered into 
the text. However, the text classes (or applications that don’t use the text classes) will then 
call the keyboard’s transliterater, which will replace the accent and base character by an 
accented character. 


Transliterater Example: 


Key Pre-transliterate Display 


b b b 
option-u b : 
a b 

d b 


generic quotes 
sneral script 


Transliteraters can perférm many other functions: for example, they 
(".") by right- and lefthand quotes (“,“,,”). They can also be used 
transcriptions for any anscription is simple and, 
converting from rom tagana for Japanese, cai 


Input Methods 


A keyboard input method supplies a fr 
ideograms: generally the Han ideograms 
ideograms may have originated as drawings: 
association is now not generally recognizable 


Background, 


For those who 
moment that E 
word or perhaps sy ; 
The number of English words.is:clearly too large to represent on a keyboard 
different methods arise to input characters. 


,5 


The most popular of these allows the user to type in characters in a phonetic transcription, 
which is automatically translated into ideograms (other methods—including handwriting 
analysis—are also possible, and can be used in addition).Let’s suppose that we wanted to enter 
the ideographic sentence: 


iscuae 


The artificial logographs in this example are the in the following table. We also include real 
chinese logographs for comparison. 


Fake Logograph Chinese Logograph 


= 
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2. Cy neighbor a0 
| (man/house) | (side /dwell) 


ee 


ound /location) 


We would type our desired sentence in phonetically as: unayburredhurudres (remember that 
there are no spaces!). As we type, the input method parses the text grammatically, and 

converts phrases to the corresponding ideograms (as far as it can). Since there may be a number... 
of renderings, the process e in. a 


1200812 


Even once the sentence is complete, the ideograms are not correct. It requires additional 
knowledge beyond syntax to get a correct result, since syntactically both the forms: 


Det.-Noun-Verb-In. Object- Det.Noun e.g. “A neighbor read her a book”, and 
Det.-Noun-Verb-Pos. Pronoun: Noun e.g. “A neighbor read her address” 
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are syntactically correct. So, the user needs to be able to modify the transscription by choosing 
alternative renderings. 


With current technology, this is done by either scnaie the phrase or segment length (in this 
case, indicating that udres is one word), or by selecting an alternative ideogram (e.g. manually 
choosing ig instead of Cy. 


Unfortunately, most sentences are much more complex than this—especially in Japanese—and 

have many more alternative phrase lengths and alternative readings. The number of 

homophones (ideograms with the same pronunciation) in Japanese and Chinese are very large: — - 
up to one hundred readings for the same symbol! Even when alternatives are chosen, the input 
method uses its knowledge of the grammatical structure of the sentence to filter out 

inappropriate options; otherwise the user would be swamped. (The user can choose to see all 
options for unusual readings.) 


In addition, many Japanes 
with the native phonetic k 
in with Roman characters 


(kana). 


Interface 


An input method can 
entered and converted: 


in stroke input meth, 
have the user draw’ 
already correct before the text classe 
window” for inline conversion for those 
and do not implement inline input correctly: 
eliminating such applications.) 


The application or high-level text classes are 
for input methods will necessitate the a 
selections, and d 
are a number of ¢ 


‘given time, 


° inactive targeted for conversion 


* active converte phrases (for which alternatives or different lengths ‘can be chosen) 
* unconverted text (generally phonetic), 
e untransliterated text (generally Roman). 


The figure shows how Japanese inline input might look while in progress. The sentence being 
input, called the active input area, is outlined with a solid line. Notice that it starts in the 
middle of the first line and ends in the middle of the second line. The text outside of the active 
input area does not participate in the conversion process. The phrases which have already been 
converted, and the un-converted input are outlined with dotted lines. The un-converted 
phonetic input is followed by a single romaji letter. The insertion point is after the romaji 
letter. 


———$—$<<— 
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Transcribed 
Active Input Area Segments phonetics 


Transcribed Untransliterated 
phonetics roman 


The following describes h 
time. This is only one poss 
As the user types text i 
be visually distinct fro 
being processed. As tex! 
example, as romaji in 
identified and conver! 


When the input meth¢ 
or it may not choose 
able to make adjusts 
could be done by pointing 

commands, such as the left and right'arr 
it must be given a visual appearance diffe 
the text in the active input area. 


e rest of the app 
§ processed, the contents of the active inp 
S transcribed into kana by transliterater 


The user can change the segmentation by indi¢ 
one (phonetic) character longer or shorter. (No 
character shorter « er, and is thus the ‘sami 


The user can display alterr 


by typing some sequence of commands like the enter key. Alternatives can be selected either by 
changing to the next homophone in-place, or by bringing up a floating window displaying all 
homophones, from which the user would then choose the correct homophone. 


Text editing within the active input area cannot be the same as text editing elsewhere in the 
application window because of the special actions the user needs to perform on the active text. 
The distinctive visual appearance of the active input area indicates to the user that this is the 
case. 


Different levels of functionality could be supported by different input methods. For example if 
the user were to delete a character from the middle of a segment, the information that an input 
method maintains to process the active input area could become invalid. On the other hand, 
most input methods will probably allow the user to freely edit the un-converted input. Less 
sophisticated input methods might wait until the whole sentence is typed before doing any 
segmentation, while other input methods might generate segments “on the fly”. Some input 
methods might decide to “drop” segments off the front of the active input area as the user types 
in order to limit the amount of internal storage needed. 
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The user can request that the un-converted input be converted by some keyboard command. It 
probably makes sense to have the command be a modification of the command that requests 
alternate homophones for a segment. 


The user can indicate that conversion is complete by some command like return or enter. When 
this is done the distinctive visual appearance of the active input area and the active segment 
would be removed and the caret would be placed after the newly converted text. 


In summary, users need to be able to perform the following actions on the active input area: 
¢ Type in 5 
¢ Change the transcription method or the input method 
¢ Change the length of a segment 


¢ Choose another homophone for a segment 


e Edit text in active i 
e Convert un-converté 


¢ Indicate that con 


Applications need to co 
standard human inte 
Methods for performi 
cursor keys and com 
methods: a user sho 
text! Note that man 
active input area, 


o the input method 
e for input methods that does not conflict: 
hese actions include pointing and clickin 


to provide a 
cation interfaces. 
mouse, and typing 
’portant for oe 


Users must also be able'to’switel 
quickly, since it is often the case th 
particular character, for example, and neé 
character. Input methods also provide dicti 
the dictionaries used by the method. For exar 
dictionaries: a user may indicate a phonetic 
category, for example..They may also want t 
dictionaries. Die f epecateed terms 
independent o 3 


In the case of inti tion t 
the input service chang input area and the segment boundaries 
deactivation); only the application knows where characters are on the screen and how to alter 
their visual appearance: when the user uses the mouse to indicate a particular segment, only 
the application can do the mapping between mouse position and character positions. 


Given this division of knowledge, the input service must be able to request the following 
functions from the application: 


To contrast this with the current situation in Blue, the majority of applications there 
depend upon a floating conversion window which pops up with any keystroke. This 
window supports the same range of features that we discussed above, but the lack of 
integration causes a number of human interface problems. It would be like having to bring 
up a dialog every time you wanted to enter some text into a document: it is very modal and 
quite distracting. 


A number of applications on the Mac and on other machines have already incorporated 
inline input methods. 
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e Replace the text in the active input area or in segments 
e Change the segmentation in the active input area 


e Change the active input area (e.g. change active text to inactive) 


The application needs to keep the appearance of the screen consonant with the text and 
segmentation structure required by the input method, including special highlighting for visual 
feedback of this structure. 


User Font Editing 


Unfortunately, the set of ideographs in use on Asian systems is not a closed set. For example, 
obscure variants of characters are used for personal names; and, unaccountably, people wish to 
be able to type in their own names (as many people in Pink have graciously pointed out, this 
would all be much easier if they just used English). 


p new characters. We have this 
ng these characters need not: 

eeded for outline font creé ’ 
‘(called radicals), so usé Select, position 
form a new charact 


In order to do this, end-us 
on the Mac, and must exté 
same kind of sophistica 
characters are formed 01 
and scale the pre-formed 


Once this has been do: 
can be entered in keyb 
a character code ran 
specific character co 
user just does not 


and the user has picked a Unicode charagt 
s and/or input method dictionary. Ths 

: de user range, or pick: 
a.the character code: 


In order to avoid 
document or send it in transmissio 
unicodes and their graphic represen 
characters defined on other systems the gra 


Text Analysis 


Text analysis class ovide for pattern sub 
character proper 


Pattern Su 


Applications often wish to present composed messages to the user, where a number of strings are 
concatenated. However, simple concatenation neglects the fact that different elements of a 
sentence are presented in different orders in different languages. To avoid this, the application 
should use substitution within a string, where the order and context can be localized to fita 
particular language.® For example, a filename and disk names would be substituted within the 
text “Copying file from sourceDisk to targetDisk”. In another language, the order of the 
element of this sentence might be: “Onto targetDisk from sourceDisk file to-copy”. Pattern 
substitution can cover most cases where messages must be composed from dynamic elements.’ 


On the Blue Mac, this roughly corresponds to ParamText, which is limited to use with 
dialogs and unstyled text. 


Although pattern substitution goes a long way towards satisfying the requirements of 
composing messages in different languages, a full solution would take the grammar of the 
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Since use of styled text will be universal in the interface, we propose using special styles (or 
even icons?) to represent the replaced elements, instead of special symbols (40, “1,..., 99 are used 
on the Mac). That is, rather than type in special characters, in order to form a pattern the user 
would select the text and mark it as variable (meaning that it will be replaced in pattern 
substitution. 


If there is this special style, then a pattern could be preprocessed to determine the locations of 
the elements to be replaced. The contents of the style could indicate formatting options for 
numbers and other generated elements. The style would have to be non-merging: two adjacent 
runs having that style should not merge internally. 


Text Service Management 


As far as we understand from the System Architect, text services such as spelling checking, 
hyphenation, grammar checking, translation aids, lexicons, root extraction and noise word 
filtering (for context retrie i iltert le text—see below), etc. will be handled 
automatically by the tool jurse, very language sensitive,:s6 
assume that the internatic closely together with the.te 
define the interfaces. { 


Transliteration 


Transliteration is used 3 given language. 
keyboard to 


t 


onvert between scripts that can be used; 
EAE anguages such as Japanese 


transliterations obei 


¢ Uniqueness 
Transcription from native to for 
cannot be transcribed to the s 
distinguishes between a retroflex 
them onto the same symbol “t’”. 


Completeness 


Native to foreign s 
symbols will map: 


Examples of rules: 


cho vv b & 


sentence into account, substituting different text when the replaced elements have 
different number, gender, etc. 


The forms of agreement are not easy to predict for your average programmer: for example, 
some languages have three different numbers: singular, dual and plural. Even English 
originally had this: instead of just two first-person pronouns me and us, there were mé, 
unc, and us, where unc meant the two of us. We will not attempt a “full solution” in Pink 
1.0. 
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t[t] ise i 
to isp : & 


Using these rules, chotto can be transliterated into Hrot&. 


Transliteration may be dependent not only on script but also on language. It is also inherently an 

nx n problem: expecting to transliterate from Russian to Hindi by using a series of Cyrillic- 

Roman and Roman-Hindi transliterations is doomed to failure, since the transcriptions used to 
represent non-Roman letters will vary depending on the script being represented: in some cases 

th will represent the sound found in thick, while in others it is an asperated t. - 


Transliteration can be used not only for inter-script transliterations, but also for intra-script 
transformations, such as for accents (replacing dead-key behavior—see Keyboards), or a 
change generic quotes (‘book’) to directed quotes (‘book’), or even glossary-style behavior.® 


They are also used for language-s 
case and back, creating titl 
stripping diacritical marks 
these transliteraters coul 
maintaining the original 


ific processing such as converting text from upper to lower 
tant Words Capitalized”), and: 
lities are only desired for..di: 
form and not the backi 


Character Transcoding 


A TTranscoding conver 
Note that individual 
UniChar converts to ! 
of a number of Codé 
consistent format. For 
while another converts to JIS Ja 
conversion round-trip cannot be gua 
encoding standards, there are multiple repr 
The round-trip from a foreign standard into U: 
equivalent Heng: however. 


as Blue) and back. 


When UniChars are converted to a foreign encoding, a similar list of font numbers and text 
starts can be generated. 


When the foreign character encoding uses in-line character set shifts (such as ISO 8859, which 
uses escape sequences to shift), then the font specifications are neither used nor produced. 


Note: the main interface differences between Transcoding and Transliterating are that 
transcoding converts to an arbitrary byte-stream instead of another TBaseText object. 


8 Whereby abbreviations can be automatically expanded as you type. For example, 
whenever I type “SANE.” a transliterater could convert that text to “Standard Apple 
Numerics Environment.” 


9 - True title text requires use of a title-filter text service in order to eliminate particles. 
Otherwise the titled text will appear as: “With The Important. Words Capitalized.” 


I a an a a a Se 
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Character Properties 


Additionally, a number of global character properties are accessable, indicating which classes 
(in the non-OOP sense) characters belong to. These properties are independent of language, but 
might be installed with particular languages. That is, the properties for an Ethiopian letter 
might not be available unless the Ethiopian language is installed. The properties include such 
items as: 


1. classifications: letters, diacritical marks, digits, whitespace, etc. 
2. directions: character direction, run direction (for use in layout) 


<It is an open issue where there ought to be a single table for the system, or that there is a 
collection of modular tables, where the installation of a language may add a new table.> 


Word Boundaries 


and 


Even in English, word bour 
grammatical parsing it is 
appreviation word (“etc.’ 
a certain constraints: they @eneral case (even at.t 
anomalities), and they mist be easily modifiable for localization. Thi 
implementation uses a: dene mechanism that allows either the 
state table to be easily:mc 
languages or purpose 
lookup), the standard 


out dictionary word-lookup 
riod endsa sentence 0 or is: 
ie word boundaries 


Subject to 


Internally, the stan 
of word classes. It the ; 
Two different start states are 
Clients can simply use the standard table 
classes. 


Source: 
Select: 
Wrap: 


To use the standard word iterator, you will use ask TLocale for a wordimae object. Once you have 
it, you will create a word iterator from it. You will then provide the text and offset that you 
are starting from, and whether to use the previous or following word if that offset is on a 
boundary. You can then cail Current to the get the word break around that offset, or Next, 
Previous, and Nth to get successive word breaks. Nth(0) is equivalent to Current; Nth(1) is 
equivalent to Next, and Nth(-1) is equivalent to Previous. First will reset the current word to 
the first word in the text, while Last will reset it to the last. So, to get the 3rd word, call First, 
then Nth(3); for the third from the end, call Last, then Nth(-3).11 


10 Unicode does have specific periods as well as the generic period: if an abbreviation 


period is used, then there is no ambiguity. 
11. We could add utility routines to do NthFromStart and NthBeforeEnd if people thought 
them useful. 


a  rep os 
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In addition, calls will be provided for doing language-sensitive intelligent cut & paste. 
Intellegent cut & paste ensures that cutting a word preserves word-breaks and minimizes spaces, 
while pasting will insure word breaks around a pasted word. For Roman and many other scripts 
this involves inserting or deleting spaces where needed: other scripts may not use spaces the 
same way. 


Open issue: we could support sentence selection using essentially the same mechanisms. In 

general sentences are not as clearly distinguishable in some languages (such as English, etc.) 
because of ambiguities between sentence period and abbreviation period, but it would be more 
international than what MS Word does now, for example. : 


Text Collation 


Text collation ordering includes provision for a number of very significant features required for 
proper comparison and sorting of text. 


a) strong ordering (A 
b) weak ordering (A 


e) ignored characters (ax < a-x < a-xy). 


Expanding characters 
We will use the notati 
character and inser 
ordered as if it wer 


s if they are inserted after th 
ean. that “ze” is compared, 
e case where & 
the “ze” order 


when comparing. 


The specific characters that I 
< “a” is a weak ordering in G 
but not in English, etc. Orderings can vals 
German ordering, for example, to get the o 
character (aex < 4x < aexx). 


Note that no character encoding contains enou 
ordering: for example in the Macintosh, simpl 

a) WAM go UF ” < “N” < “Oy < 
The standard c nclude th 
may be required® ; a 
example, the abbre ¢} mbip ous, ;, and may be sorted either as 
This behavior, however, could be subclassed. 


Creating a Collation 


The programmer can append a new string to a TCollater, in which case it is ordered after the 
very last string. The programmer must gos if it is a weak ordering (“a” < “A”), and whether 
the string has expanding characters (“a” < “2”/“e"”). Null ($0000) is a special character, 

which is inserted in a TCollation at eaten time. It is always ignorable, and any character 
only weakly greater than it will also be ignorable. Any character not in the TCollater will be 
ordered strongly before all other character codes. 


For example, we could build a new TCollater as follows: 


Add Result 

<a => null <<a 

<a => null<<a<a 

< @/e => null<<a<a<@/e 
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<A => nul<<a<a<@/e<A 


<<b => null<<a<a<@/e<A<<b 

<B => null <<a<a<@/e<A<<b<B 

<<c => null<<a<a4<e/e<A<<b<Be<<c 

<C => null<<a<a<@/e<A<<b<B<<c<C 

<<ch => null<<a<a<@/e<A<<b<B<<c<C<<ch 

< cH => null<<a<a<@/e<A<<b<B<<c<C<<ch<cH 

< CH => null<<a<a<@/e<A<<b<B<<c<C<<ch<cH<CH 


Using a TCollater 


To use the standard collation, you will ask the environments mechanism for your TLocale, then 
ask the TLocale for a TCollater. In simple comparison, the TCollater takes two strings and 
compares them. If the user supplies the two optional text indices, then the method will ret 
the positions in the two s ifferés 
the first point at which t 
point at which there is a 
identical (and if suppli 
text). 


calf there is one. Otherwise it 
s one. Otherwise, the stri 


P. 


the first language in the 


Two characters of the same lang 


Units 


A Unit can associate unit quantities and their textual representation in a given language, and 
perform conversions to other units. Both plain and abbreviated forms can be included. For 
example, meter can map to "meter", "metre" or the Greek, Cyrillic, ete. equivalent; USDollar 
can map to "$" or "$US", etc. A TLocale can also specify the default units for a given measure: 
English vs. Metric, the default currency, etc. — 
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In terms of conversions, units generally fall into three categories: simple units such as feet or 
meters, predictable units such as times or dates!2, and volatile units such as currency rates or 
Apple stock prices. We will initially support time and date conversions, and perhaps some 
degree of simple unit conversions: volatile conversions are not exactly high on our priority list. 


Time 

Time and date are special units, and require more support. The basic system time is measured in 
seconds since an arbitrary base date (e.g. 00:00:00 Jan 1, 1904 on the Mac!) and require a 

dynamic range of approximately 1013 seconds before and after the present (a comp—64-bit % 
two’s-complement integer—is used on the Mac). See the Toolbox time routines for more 

information. 


Time zones, Calendars and DateTimeFormats are used to convert this form into specific human 
measurements (see below). 


Civil Dates 


Civil dates are used to de 


spans of years. Once constructed, 
or backward. For example, given a TTime [ee 
“Thanksgiving”, the client can find the fir 


The system will be shipped with a set of locali: 
add new civil dates to the system. (It is easy to 
of specific dates in:given.years, or to give slig 
Thursday in Nove 


Planning Yez 


A planning year is a collecti dates and work-week information that c 
project planning. Planning years can be created or edited by users and applications. Planning 
years will return the number of workdays between any two TTimes, and also allow iteration 
through workdays. 


12 Strictly speaking this is not true, since with some lunar calendars still in use, the date 
depends on the visible phases of the moon. With bad weather, the month in a particular 
location can start as much as three days later. We do handle this as a special case. 

13. 


The choice of origin is not particularly important, and will be hidden by the Toolbox 
classes. 
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Time Zones 


A TDaylightZone maps from a GMT!4 datetime to a local datetime and back. TDaylightZones 
are of finer granularity than regular time zones, since any two locations are in the same zone just 
in case they currently have the same daylight-savings periods, and have had the same in the 
past. For example, Arizona and Colorado have different zones, even though they are in the 
same time zone, because Arizona does not have daylight-savings time. Zones internally use a 
collection of civil dates to find the starting and ending dates for daylight savings time. This 
functionality provided by zones is a superset of the UNIX time zone mechanism, and is also 
table-driven. 


In addition, zones also contain geographic information which allows us to provide a direct- 
manipulation interface for choosing zones. The human interface for setting the clock time 
should encourage users to set their location, since otherwise date stamps on files and network 
transmissions will be incorrect. We. will ship.a. number of zones to satisfy most needs; it is 
unclear whether we can m asy ene to allow user-crea 


picking a location ona 1 


Note that local times are iot continuous, and may overlap. E.g. Oct 


tween 1:00 am and 2:00 am, while April 21 


is handled by the 


Daylight rules can « 
former, noon is alwé 


the starting transition : 


Calendar 


Given a location and a daylight zone, a Calen 
fields and back. Examples of calendars are G 
include: era, years month, day, hour, minute, 
dayOfYear,... : 


Calendars also r 
dates, and the ran 
toggling, where fiel nd: ¢: z Hi 

month upward in the da 9, 1989” results in “Jan 29, 1989”. When toggling, other fields 
remain unaffected, where possible—toggling the month upward in the date “Jan 29, 1989” from 
January to February cannot be done without changing the day of the month. 


14 Greenwich Mean Time. Actually, we will be using UTC2 (Coordinated Universal Time) in 
| our standard calendar calculations. UTC2 adds leap seconds during some years to account 
for variations between Universal Time and International Atomic Time (TA1). UTC2 
includes corrections for Chandler wobble and for seasonal changes in the Earth’s rotation 
rate. 


15 Some systems have time servers to make sure that computers share the same time 
(hopefully our OS will have this service). One problem with these systems is that users 
can't easily set their own clock to something different than the net time. By using a 
different standard time offset, this can be done. 
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The field ranges and toggling can be used in the human interface for setting dates and times (e.g. 
toggling as in the Alarm Clock). A view will be provided for editing time (there are two 
important variants: absolute and elapsed time). 


Calendars are not table-driven, but they may require some Bercian data storage for efficiency 
(e.g. the Arabic Lunar calendar on the Mac has to compute sunset and phases of the moon, so it 
uses a persistant caching mechanism). Calendars are not specific to language: language-specific 
formatting is handled by the DateTimeFormat. 


Calendars must be set with the current location. Different fields of the calendar can then be 
gotten and set. The calendar keeps information as to the sequence that fields were set in. 
Whenever a field is gotten from the calendar, then the information in the calendar is 
validated. Any of the fields may change in value: the most recently set fields have priority. 


For example, suppose that we set the dayOfWeek field, then the year, month and day, then 
get the dayOfWeek. The dayOfWeek field will be altered to be consistent with the year, 
month and day, since they .were.set-Jater..If.we.then.set the dayOfWeek and weekOfY ear... 
fields, and get the day fiel¢ 
internal time (seconds sin 
gotten, then the day corr¢ 
the internal time is got 


A service is available fc 
divides it into three fie! 
integral number of se 
available: solar time, : 
fields can also be co 


Three options are 
nds). These three 


We also provide ser 
conversions, sunset titres ar 


DateTimeFormat 


A datetimeformat contains mappings from 
mappings can have variations, such as abbre 


“Friday”. .. Any field: 
names for the das 
calendar. When 
can be ee 


1, 


fmat for each 


Ss nu rmats: plain, zero padded, ordi 
Numerals], <length>; see NumberFormats) 


2. text (plain, abbreviated). 


The formatted fields are substituted into a text date pattern using pattern substitution. If no 
date field text is available, then numbers will be used. (The following example illustrates the 
substitution, but is not necessarily the method we will use. The substitution pattern will contain 
some data indicating options on the field format): 


Pattern: “hour:minute ampm zone on dayOfWeek, month day, year zone era’ 


hour: number-only, mod 12, one-based 
minute: number-only, zero padded 
ampm: 
zone: abbreviated 
dayOfWeek: 
month: abbreviated 

” day: ordinal 
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year: 
efa: abbreviated 

Date: 1,493,527,842.000 seconds 

Result: "10:08 am PST on Sunday, Oct. 13!h, 1958 A.D." 


A newly-created format will have simple numerical mappings and a default pattern based on 

the system language. Additional text names and abbreviated text names can be added for any 

field values, and the pattern can be changed. The text is of type TStyledText for generality. 

(Note: the field text might be common to many different patterns, but this model forces them to 

be stored separately. An alternative architecture breaks patterns and DateTimeFields into 
separate entities, with the latter shared). : 


DateTimeFormats will also scan text for date and time, matching against a specific pattern. 
The scan will stop at the end of the text, end of the pattern or first inappropriate element. The 
length used by the scan will be returned, as well as any fields found. The scanning will match 
exactly if possible. Otherwise heuristics will be used, including: 


1. skipping over nonz 


2. using calendar fie le matches: 1958/12/ 


3. using the order 


A number of standard dat E 
absolute ids (names), ‘ou use a date 
format by id, then it v 
shortDateFormat wi 
standard formats ha 
user creates a new {i 
spreadsheet: “Tuesd 
displayed in a readable Germ. 
fields is not the same in these two ‘fan 


guess at the scannin 


0/21/89” in America, and “21 | 


Numbers 


Number formatting involves converting a bina 
programmatic control. Number scanning invol 
piece of text, and ret#rming a number and the c 


international ani 


sophisticated clien 
outliners. These pt 


matting of numbers with th y 
00000, ($10,000.00) for -10000; ete 


Number formats include integers, decimals, outline numbers (e.g. Roman numerals, letter 
numerals), and ordinals (1st, 2nd,...). We will provide both formatting and scanning of numbers 
based on local conventions (e.g. 5,280.0 vs. 5.280,0). A superset of the functionality on the Mac is 
provided, whereby pattern matching allows users to get Excel-style functionality while being 
compatible internationally. Number formatting will also include outline numbers, such as 
Roman numerals, lettering, etc., and their equivalents in different languages. In general, these 
will be code based, although tables of localized number components (decimal separator, etc.) 
will be available. 


Number scanning will provide not only for the standard Western numerals (decimal 0..9), but 
also for more unusual systems such as Chinese numbers and outline numbers. Not that in Unicode 
that the numbers that have significantly different shapes in different scripts have different 
codes: this is accounted for in both scanning and formatting. 


The formatting process first involves producing a number format pattern. This is done by using a 
localized NumberComponents object to convert a text string as might be supplied by the user, 
such as “###,###.00” to a NumberPattern. This NumberPattern can also be converted back toa 
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text string using a NumberComponents, which may be different. For example, converting the 
above NumberPattern using a French NumberComponents will result in “###.###,00". 
NumberPatterns may have multiple parts, allowing different formats for positive numbers, 
negative numbers, Zero, positive infinity, negative infinity and NANs (as on the Mac, we will 
be depending on SANE conversion routines internally). 


Text Format 


NumberPattern 


##,###.00;(##,#4#.00) 


(English; 


(French) 


,00;(##.###,00) 


Text Format 


By using a Number 
the left. Clients can: 


more forgiving than the at, SO: 
NumberPattern using an English Numbe: 


Extended 


NumberCom 


NumberPattern 


(3.456,7) 


Formatted Text Extended 
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Unicode 


This document discusses issues and design considerations involved in the allocation of character 
codes for the standard Apple sixteen-bit character set (Unicode). This character set is designed 
to be an efficient, internal process code. It is also a foundation for conversions to and from 
different interchange formats (MS DOS, current Macintosh, ISO 8859, etc.). 


Background 


The Unicode project at Apple began as a quest to remedy the most serious flaw in the 
architecture of multilingual text handling on the Macintosh: the overloading of the font 
mechanism to encode character semantics and properties and the use of multiple, inconsistent 
character encodings based on conflicting national standards. Unicode envisioned a uniform 
method of character identification that would be more efficient and general than the 
Macintosh script systems ai ript (i.e. font)-specific software fo 
display and editing of all if text will meet two main 


¢ Elimination of specia 
character encoding 
applications and s 


on code for dealing wi: 


cess of localizatio ing testing for 


¢ Making a larger rai se of characters available to meet the requit 
quality typesetting and desktop publishing. : 

As a result of our res¢ a, 
meet the requirement 


* Completeness. 
ever be used in:geé: 
standards showed 


e Efficiency. Plain text, composed of a seq 
extremely useful model. It’s simple to pars 


preferable to the m 


current use On many machines. Text compression is important, but need not be defined by the 
character code standard. There are many different ways to compress text depending on the 
particular application. 


16 The initial release of Unicode will contain approximately 25,000 characters of all the 


world’s major scripts, including some 18,000 unique Han characters defined by industry 
standards in China, Japan, Korea, and Taiwan. This is more than sufficient for modern 
communication, including such classical languages as Greek, Hebrew, Latin, Pali, 
Sanskrit, and literary Chinese that may be required by literate non-specialists. Obsolete 
scripts such as cuneiform, runes, hieroglyphs and additional Han characters used in more 
specialized research will be added as required. 
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Alternative Standards 


Not wanting to duplicate effort, we also considered the efforts of other companies and 
international standards bodies in the development of a universal character code set. There is 
currently one other general multibyte character encoding under development, ISO DP 10646. 


The main difference in goals between the Unicode and ISO DP 10646 is that the latter is 
designed to maximize transmissibility by current products, while Unicode is designed to serve 
as an efficient 16-bit internal process code for current and future products. 


The heart of DP 10646 is the two-byte "Basic Multilingual Plane” (BMP). To maximize ¥ 
transmissibility, DP 10646 reduces the space for graphic characters in the BMP by 29,055 codes 

to avoid conflict with 8-bit control codes. The remaining graphic character space is further 
reduced by separately encoding the Han characters (Chinese, Japanese, and Korean 

logographs) by language, so that 22,594 cells are allotted for the approximately 10,050 unique 
characters in GB2312-80, JIS:X.0208 KSC.5601.This leaves no room in the BMP for the nis 
traditional Han characters t . 

extensions to the GB and 
codes for glyphs. 


A 16-bit code space pot 
provides only about 17, 
Since this is insufficient 
coding, with various 
addressing characters 


Methods & S 


Apple and Xerox!7 
Unicode. Xerox and Apple were soon joi 
companies, including Claris, Metaphor, \ 
and others. This cooperation with other co 
contributions in different areas, and increased: 
future. 18 


Unicode Draft 1 was iss 


Chinese, Japanese, 
due on June 1, and finali 
be added in subsequent ve 


We are also active in the ANSI X3L2 multi-byte character encoding committee which is the US 
national body dealing with ISO 10646. Our goals in that effort are to: 


e ensure that Unicode will meet the conventions of an international standard, 


e influence the 10646 design in the direction of Unicode (failing that, ensure that the 10646 
design does not preclude transcoding with Unicode), 


Unicode. 


17 Xerox is also very active in the area of multilingual operating systems (though not in 
terms of units), and had realized that their character encoding methods could also be 
significantly improved. 

18. 


Xerox has been particularly helpful in the design of Unicode and in printing the draft 
Unicode charts. 
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* encourage other countries and companies to consider the advantages of the Unicode 
approach over 10646. 


We were able to get approval from the ANSI X3L2 for including the major Unicode principles 
within 10646 (Document X3L2/89-195: “Proposed Modifications to ISO DP 10646”, a U.S. 
National Body Position). The principal motivation for the ANSI support of this proposal was 
to avoid two, separate multi-byte standards. The initial international reception for this 
change, however, has not been promising. 


Design 


Developing a character set consists of two steps: selecting the repertoire of characters to go into 
the set and assigning codes to the repertoire. Many coding standards have run into problems 
because they attempt to mix formatting codes, compression methods, or glyph encodings into 
their standard. 


Unicode Characters are fi 
exclusively, the letters, pt 
including foreign languag 
reside only in the mach 
contrast to characters, ¢ 


epresenting primarily, but not 
hat compose natural language 
¥F technical documentations 
‘on disk, in what we c 


differ considerab 
In allocating char 


single glyph shape to represent clare : 
Unicode deals only with character codes. 


and fast rules. Hi the following general princip es. 


* Constant-Width, . Just as with simple ASCII text, dev not parse 
text for shift sequences to determine character boundaries or encoding. The elimination of 
the requirement for shift sequences also permits efficient random access of characters. 


Unicode is no different from any other binary data and can be compressed to reduce storage, 
transformed for transmission over 7 bit or 8 bit lines, or transcoded to and from other 
character encodings. There are many algorithms available for performing compression and 
transformation (e.g. Unix btoa which converts 32 bits to five 7-bit ASCII characters): 
Unicode itself does not currently specify any particular methods. 


¢ Full Encoding. Unicode reserves room for a limited number of control codes; aside from these 
it uses the full 16-bit range to represent over 65,000 graphic characters. 


¢ Complete Encoding. Unicode provides character codes for characters used in the computing 
and the publishing industry around the world. It draws from a base of national and 
international character encodings, including: ANSI Z39.47-1985 ( bibliographic Roman), 
ISO 5426-1983 (bibliographic Roman ), ISO 5427 (bibliographic Cyrillic), ISO 5428-1964 
(bibliographic Greek), ISO 6438 (extended Roman for African languages), ISO 6861 
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19. 


(Glagolitic, Old Cyrillic, and Romanian Cyrillic), ISO 6862 (mathematical symbols), ISO 
6937 (Western European Roman script), ISO 8859/1-8 (8-bit sets for all European Roman, 
Greek, Cyrillic, Arabic, and Hebrew), ISCII (India), GB 2312-80 (China), JIS X 0208 
(Japan), KS C 5601-87 (Korea), and CNS 11643 (Taiwan). It also includes de facto company 
standards, such as the Fujutsu extensions to JIS. 


Preservation of Base Distinctions. For ease of transcoding, Unicode preserves differences 
found in the base standard encodings mentioned above. For example, Greek "Omicron" (O) is 
distinguished from English "Oh" (O) because they are distinguished in ISO 8859/7. 


Pure Character Encoding. Other than what is required to preserve base distinctions, : 
Unicode does not attempt to encode features such as language, font, size, positioning, 

glyphs, et cetera. For example, it does not preserve language as a part of character 

encoding: Chinese "zi" (=), Japanese (=) and Korean "ja" (=) are all represented as 
the same character code, as are French "i grecque" (Y), German "ypsilon” (Y), and English 
"wye" (Y). ; 
The distinction betwee 
function of a higher-le 
itself. 

Dynamic compositi 
composed forms. C 
are allowed for c 
However, because 
with modifying d 
and diacritic ch 


‘ditional letters 
of base letters 


Unicode accents 
means that they. are 
example, the diaeresis “ can be'es 
languages using the Roman scrip 
limited use, hence, slashL is treated as 
from two characters. 


This extends to non-Roman languages as 


does separate case ES A”) of the same letters. 


Common Characters. encourages the borrowing of characters from 
avoids duplication except in the following cases: 


a. Operators and well-known constants borrowed from Greek (e.g. 2 or “pi”, and ¥ or 
“summation”) and other scripts are allocated separate character codes. However, this 
is not true for Greek letters used as variables. 


b. Apparent style variants!? with specific usages (e.g. the script form “a” in the 
International Phonetic Alphabet, which represents a low, back unrounded vowel) are 
assigned separate character codes. 


Han Unification. From the above, it follows that Unicode does not define separate codes for 
the Han characters (hanzi, kanji, hanja) used in Chinese, Japanese, and Korean. In unifying 
Han characters, Unicode follows these rules: 


As noted above, for each script we assume a single font family and style to represent the 
archetypical shape of a character. A style variant is any departure from this base shape. 
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a. The initial repertoire is based on the four major standards for Han characters: GB 2312- 
80 (China: 6,763 characters), JIS X 0208 Japan: 6,349 characters), KS C 5601-87 (Korea: 
4,888 characters), and CNS 11643 (Taiwan: 13,051 characters), and the approximately 
5,000 characters of the proposed extensions to the JIS standard. 


b. Character identity is preserved over the combined standards. Where variant forms are 
given separate codes within one standard, they are also kept separate within 
Unicode.29 This guarantees that there will always be a mapping between Unicode and 
target national standards. 


c. In determining whether or not to unify variant forms across standards, Unicode follows - 
the guidelines published by JIS.21 Where these guidelines suggest that two forms 
constitute a trivial (wazukana) difference, Unicode assigns a single code. Otherwise, 
separate codes are assigned. 


¢ Digraphs. Unicode provides digraphs such as Dutch I i for compatibility with existing 
standards. Otherwise, 
powerful to guarantee 
collating, compariso 
below). 


Future Expansi 


In the first implementé 
characters required f 
(the Han characters. 
national standards it 
common use on co 
symbol set to be co 
assigned in the private user space. Hos 
symbols and other characters for commortt 
leverage the efforts of other companies to | 


registry. 


20 For example, JIS assigns six characters ( 23-85, 49-88, 49-89, 49-90, 49-91, 78-63) for 
variants of the character ken “sword.” Unicode preserves all of these. 


21 These guidelines are found in the Japan Industrial Standard Jouhou koukan you kanji 
fugoukei (Code of the Japanese (sic) Graphic Character Set for Information Interchange) 
C 6226-1983. §3.4 Kanji no itaiji no toriatsukai (The handling of variant Han characters). 
Though written with Japanese usage in mind, they are general enough to be applied 
across all three languages. 

22 


Many of the symbol characters, such as the Roman numerals, have been added only 
because they exist in some standard. 
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Unicode Codespace Allocation 


0000 

ALPHABETS (8 K) Alphabets, Syllabaries, IPA, etc. 
1FFF 
2000 SYMBOLS (4 K) Punctuation, Math, Technical, Dingbats, etc. 
2FFF 
one User area. Can be transmitte by private 
SFEF agreement. 
neOe Chinese zhuyiz 
AFFF Korean hay: ols, and punctuation 
5000 

FUTURE EXPANSION Spill over from alphabetic or Han zones as require 

FFFF 


assigned Unicodes reserved for future assignment 


<o private, never assigned 
RLY XI 


* FFFF is permanently reserved as an application 
specific sentinel value (e.g missing character, etc.). 
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Code Assignment 


Unicode is divided into five zones: Alphabetic and other scripts having relatively small 
character sets, Symbols, User characters, Auxiliary characters for Chinese, Japanese, and 
Korean, and Han characters. The alphabetic zone covers alphabetic or syllabic scripts such as 
Roman, Cyrillic, Greek, Arabic, Devanagari, Thai, etc. The symbol zone includes a large 
variety of characters for punctuation, mathematics, chemistry, dingbats, etc. The user zone 
(about 4,000 code points) is used for defining user- or vendor-specific graphic characters. The 
Chinese, Japanese, and Korean auxiliary characters include punctuation, symbols, kana, 
zhuyinfuhao, and single and composite hangul. The Han characters subset provides for over 
44,000 logographic characters common to Chinese, Japanese and Korean. Unicode Draft 1 
currently covers the complete repertoire of 16,400 unique Han characters defined in the GB, 
CNS, JIS and KSC standards. Unicode version 1.0 will extend coverage to include 
approximately 18,000 chara 


° Unicode is “fully codé 
specifically as “cont 
and should not be tra 


v0 codes ($0000-$0020) are; 


Certainly naive use of ASCII does not wi 
holds true for upper/lower casing, whic 
the Unicode character code pia dog 


ae in ASMO 662 are: 


and other lan 
the basic ASMO'se 
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Section 


} Start Code 


No. Assig ed 
32 


> 
pme 
= 
| fa 
lox 
2°) 
ce 
n 
Q 
to) 
a 
2) 
_— 
Oo 
© 
© 
oO 


| Modifier Letters E0280 39 
| sé Diacritics 0300 60 
EES (Cl eee cee eee 
Dec geese tt OWING: octane vitae nd ao OM ON. es aon) lee 
ng, GOON IAN 
Armenian 0530 83 : 
ae: * rr ie -. e ES) 
PT ArabIC 0600 167 
8175 ee 1 ee, SN 7 
YC Devanagari 900 100 
Bengali -_.0980 
Tar © OA00 671. 
ennai 0a80 
ces ca acter acer 0B00 
De oe OB80 

: 0C00 78 


f Mongolian 
nctuation 


[Ss Control Character Pictures | 2360 
| ATOWS 2A 72 
Geometric Shapes 2400 65 


ee eee Basic Dingbats 2460 PY 
gee | OSC etn etc 00 cee ace 
spa ie nen nc OPUS aaa Mee ta 8 ete CO AI taeda 
tee SC eee ee ee Ce 
es epoca ca POCONO a telat nO Oe Spee in OO 


eet get) ANNA So eee ce ROMO sd ae 
EASE eee SE Sy aR IEE 
| Hangul Letters} 4130 94 
___ Parenthesized Letters 4300 F883 
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eee ee eee ale Cr eel Beene) 
eae CTS een Mee RN 
fen Han Rae 5000 18,000 


Details 


The following are particular points about the design of Unicode that specify details that are 
necessary to determine correct use and interchange. . 


Paragraph/Line Separators 


Unicode does not specify a particular character for a paragraph separator or a line separator (a 


‘ 


line separator causes a line break (e.g. 
’) but does not start a new igraph spacing and paragraph indent 
not applied. Apple will pr 
separator. (Note that th 
separator servers only t 


Specific Charac 


In many cases, current 
characters that are u 
period, dash, space, : 
characters: right & | 
en-dash, minus, h 


es of this are the. ger 
se characters, but 


There are several varieti 
to add soft-word breaks in languages Ww 
which can be used in controlling cursive for 
width non-joiner. There are also zero-widt 
space and the left-to-right zero-width space. 
word-break space does not affect joining or dir 
have a direction; the directional spaces do not 


Unicode text is store cal’ order in the backing store. Logi 
order is based on the chronological order in which text is spoken. English and ‘Het 
are shown below first as they would be ordered first in logical order, then in display order. 


23_ We will probably not use these in Pink to control direction, although we will interpret 
them properly if we receive interchanged text that includes them. 
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O Jd 3. ss 


Ae 
The Heavens and the Earth : 


ene eee eS 
PORT ORT owt OX 


In the example, the first ch 
displayed text is in the cor 
the text ordered for dis 


e string is at position 0, but 


a. Non-spacing 
Arabic and | 


b. 
c. as : orm of the “short i” ({) in Deva il 
before the charact they logically follow in the backing store. 
Sample Code Pages 


The following are sample pages of the Unicode code charts. They are followed by a sample 
page of the Han character cross-reference. The cross reference is in radical-stroke order, with 
the characters from each of the four base Han standards listed together. The numbers 
underneath each character are the code points in the respective base standards. 
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oD WwW NN Qn yA BP Ww ww = roo] 


> 


m Oo 


‘n 


Unicode 00___ Hex Draft of 2/15 


Control {| ASCII Misc. Latin1 


000 001/002 003 004 oos 006 007 | 008 009] 00A 008 ooCc ooD OOE OOF 
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Unicode 03__ Hex Draft of 1/27 


Generic Diacritical Marks 


030 031 032 033 034 035 036 {037 038 039 O3A O03B O03C 030 O3E O3F 


tote} | T fel fefals[=fofal 
iste} |] Ty fatelelefotat 
EF ay 2] [els | tl 


Uy 
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Unicode 05__ Hex 


Georgian Armenian Hebrew 


9so 051 052 053 054 055 0S6 0S7 058 | 059 osA 058 OSC OSD OSE OSF 
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Unicode 04__ Hex 


Cyrillic Extended Cyrillic 


040 041 042 043 044 O45 046 047 048 {049 O4A O48 O04C 040 O4E O4F 


pfatets{e] folel}etr}ete}e] | fo 
ejsici«{«|sie[e[s{ei=|e] | [J 
sESENES EEE? jee {is] x | | duel 
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No 


ud 
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va) 


a 


N 


@ 


ve) 


0 


m 


mn 


Unicode 20___ Hex Draft of 2/15 


General Punctuation Supers. & Subs} Number Forms Currency 


200 201 202 203 2044205 206 207] 208 209 20A 20B 20C {200 20E€ 20F 


ele | fd. fe fed | fo} 
ei-[ } | tf fo fe fifo 
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Unicode 22 __ Hex Draft of 2/15 


OCR Parts Mathematics Operators 


22A 228 22C 22D 22E = 22F 


225 228°..229 


226 227 


220 221 4 222 223 | 224 


ane 


jt] pepets|-[e[s]s[ a = 
ptt folate [-[=fefelafols |e] 
pte} fetid e[e[[sfsfefof | 
Pp ist felis l-[=fefefetofat | 
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Unicode 40_._ Hex Draft of 2/12 


CJK Symbols Hiragana Katakana- 


Tepe 
BOE 
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Unicode 41__ Hex Draft of 2/12 


CJK Mini User Space 


Bopomofo 


Hangul Elements 


410 411 4121413 414 415 416 417 418]419 41A 418 41C 41D 41E£ 41F 
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Unicode 43__ Hex Draft of 2/12 


CJK Encircled 


CJK Parenthesized 


430 431 432 433 434 435 436 437 | 438 439 43A 43B 43C 43D 43E 43F 


Feo | w | @b 
ol [ole] ele 
oy oy [ee | “) 
Ey 


(=) = (3) 

fa] fol afl 
OCC 
fol fol fale 


@ Registered/Restricted International Utilities March 1, 1990 2.1.6-42 


Unicode 44__ Hex Draft of 2/12 


CJK Squared Japanese CJK Squared Latin Abbreviations 


440 441 442 443 444 445 446 4471448 449 44A 448 44C 44D 44E 44F 


~ 


/ 


fax 
Stt 


@ Registered/Restricted International Utilities March 1, 1990 2.1.6-43 


BigS cB JIS KS Bigs fos} JIS KS BigS (os! Jts KS 
. 6% 2 # a 
1] als C34? D-120 
: | 33290 «OSI $617 
La & 1 1 4 ne 
Ada 1676 1673 ales 2528 4458 
$027 2492 : 
. eo a 7H of ae ake 
AG42 ee 3590 7943 Agsc3 4234 ra 
—_ a 
Be ae 10 # mq ww cs 
Aas eas 2623 6650 Ae 1-2291 2804 1619 ; pane, 
= 
ae) AS4G ayi9 
4G32 ae 4925 
eed, = _ —— a 6 ye L 
‘oveeela ae: — _ 
z AS47 2435 
AGS4 4093 2716 6318 Seas i 9126 
[- ‘is [- 45 fz A= 
ASS [= 3867 
A4a5? aa 3069 6330 on G23 
i A a 5 Be ise 
ASES by 
C945 4392 $618 ao 


—| 
— 


A455 e927 
es qe | te 
o~, 4810 4650 
af 
4a AR 
J 2672 9302 
7 air 
i 3072 
qe 86 TE 
: He =e 
CI4YE 4811 6711 
As Pas 
a] 3] 
2212 4666 


SEH EH 


ee es 182 1564 
oso ND 


gh gulf 


2269 4690 


4 2 
a D-166 
ie 
2480 4387 
tt ff 
4473 6905S 
AMEE 
A ees ag 
AS42 onmmne Cr 4265 
fg = S 
A543 sae nis $244 
1: {fF Aes 
AS40 uy 3204 = {4] ss as al. al au 
AN AR S 6 # 
AS41 as 4803 a ae a ss 
5 # | a ba x, aL 
c940 4609 7149 MSO 4q58Q 
fig yy J 7 # ces, 
4630 Add a3 3921 $012 606 
, 6 = 2 dF N UL 
ASEL 2216 o-41 x rr 
7K AS Z TZ | 3 ees 
ASEO 7K 30O7L 7c A. A A A io 4 tl a 
6 # aq 4 y | 8 a 
89 Asc “ 


1990.2.\%™§ Registered / Restricted International Utilities 


Y Djs Wye ye EHS SSS HAG MRIS WOE du)s HOE Hie Bee Ba 
aay i=] 

: sali SF mE HIE sald WE ME MERE SE MESE 0 Eo 
a Q 


g seis WBE Us Ajith BOS PAG HUE INE THE BE EE 


We) & oy A 


sas 1993 


KS 

ia 
$4862 
pal 
6691 
pul 
4228 


$217 
6760 
#55 

a 
9317 


UE SSE vols SKS 3 
simi wiaiBe SESE EME SIH 
Q fo) 

se AE Yo 


JIS 


s 
s 


Cal 
led 9 u v ° 
2. = @ 
Me sR RYE B/E we w 
¢ n AN fen a) 9 ‘ 
Qa 


D-38765 
~ 
yo 
1864 
ig 

0-36791 


3387 
we 
3ea¢6 
ples 
3464 
iG 
341 
77860 
DO-38 


4242, 0~-38844 


GB 
jE 
340 
sei 
4266 
a 
“ne 
fe] 
6936 
oo 
sti 
6938 
pul 
6340 
wa 
4a 
HZ 
ur 
2803 
Xe 
ih 
4923 
UE 
1737 
ea 
BE 
“51 
ik 
co 
1é 
$823 
ya 
6343 
6344 


BigS 


B068 
B06é86 
s06éc 
iG 

8060 
O3JEF 


[) food w w 
8 398 NS WE KE 


iG 
ADA2 
ide 
ADTA 
iB 
aD7C 
ia 
ADIE 
LE 
poss 
iif 
ADA3 
pu 
AD78 
ig 
ADAC 
ie 
D3F0 


et 
o 
2 

or vo fe 


IS es 


. 
vee 
1710 
0-38735 
oo 
iu 


0-348755 


0-38737 


D-38783 
id 
0-38777 
wT 
3886 
yl 
7176 
Y- 
3719 


_ 


~ 


BigS 


a 
ix 
cpo2 
iA 
co0o0 
it 
coc¢e 
ee 
cDco 
raed 
cDocr 
iK 
AAEO 
an 
AAEL 
pul 
AAEE 
i 
CDCE 
oe 
cool 
sit 
poB3 
ib 
DOB: 
iE 
0084 
es 


2.1.6-45 


Mardi 4h (99@ #5) 


International Utilities 


1990.2. f& Registered/Restricted 


@ Registered/Restricted Tokens March 15, 1990 24.7 =) 


Architecture 


Tokens are fast strings. A token is an object that has a unique id, one id per string. The token server 
guarantees that two identical strings will return the same unique id. Tokens are useful for sending 
strings within your application, or across applications on the same machine. Tokens are streamable, and 
will do the right thing — either streaming the unique id if the stream is a local stream, or streaming the 
string if the stream is across the network, or to the deep freeze. 


The system maintains a Token Server that performs the work of token issuance. The application 
framework maintains a local cache so that second and further token requests for the same string do not 
incur IPC overhead. . ' 


Tokens may be static objects. They have been designed not to go to the Token Server until the first time 
they are used. 


Tokens are most useful where.there.is.a.need.for.extensibility. An example of this is the event name 
space. In order to suppor 1 rt 
done today, instead event 
Another example is the 
integer so that it will be. 
in a integer based scher 


ing conflicts inherent 
do 


erkill. The server 
ending server messages it 
ns acros the network is 


There are definitely pl 
architecture used toké 
was decided thatas 1d.scheme would be fine. 


idea, unless of co 


reference if they are to be filled in, const refer 


A token may be invalid, i.e. not havea string. 


Static tokens ar ; the “MouseDown’ al 


used for comparist 


Static TToken mouseDown (“MouseDown”) ; 

TToken eventName; 

event->GetEventName (eventName) ; // fill in eventName 

if (eventName == mouseDown) // perform comparison with static 
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Making Whoopee 


@ Registered /Restricted Application Framework March 15, 1990 224 4 


The Class Hierarchy 


The class hierarchy for the application framework is substantial, and looks like this. Notice that most 
objects descend from MCollectible, making it possible to use them with the collection classes. 


MCollectible 
MResponder 


ee ow TGraphicApplication 
(MMessageTagsk) TView 


TLayer ‘ 
TScroller 
TTitleBar 


TWindoidTitieBar 
TMenuTitleBar 
TWindow 


eS TStdWindow 
TMenu 
—_ et 


TButton 


TOutputPort 
_ L- ToutputPortSet 
Device 


TKeyEvent 
TLayerEvent 
TDeviceAttachedEvent 
TDeviceRemovedEvent 


TToken 
TTracker 
TStdMouse Tracker 
TWindowDragger 
TWindowSizer 
TMultiClickTracker 
TEventQueue 
TModifierKeys 
TRespondHook 
TDeviceManager 
TGrafPort 
TLayerPort 
TViewPort 
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The most important classes are TGraphicA pplication from which your application must descend, TView 
and its subclasses which allow you to subdivide the screen into logical drawing areas, TViewPort which 
you use to draw into a view, and TEvent and TDeviceEvent which are created either by external events, 
or may be created by you to send messages to yourself or other applications. 


The Visual Hierarchy 


The visual hierarchy describes all the visible objects, or views, that the application framework knows 
about. The visual hierarchy is built around the idea of enclosures. Everything that you see on the screen 
belongs to — is enclosed by — another visual entity. Every enclosure is a subclass of the view class. ~ 


At the top of the visual hierarchy i is the desktop. The desktop encloses all of the windows in your 
application, as well as those in all other applications that are running simultaneously. Each window 
encloses one or more views, and views can enclose other views. This is a typical visual hierarchy. [Note: 
we should think about making the desktop a view also. That way we can encapsulate layer switchin ng 


protocol into view methods 
of the event and layer ser 


The visual hierarchy is dynamic, changing as 
new window is added to the desktop, and view: 
document's conter : 


iew. Drawing that 

ed, must be drawn into & ed by the 
application framework. af occurs at any other time must be into:a managed by the 
drawer. 


Visual, or positional, events, work their way down the visual hierarchy, from the desktop to the active 
window, to the appropriate view. Views can handle positional events because they are responders. 
When you click in a view, the application framework uses the visual hierarchy to determine which view 
the mouse went down in, and tells it to respond to the “MouseDown” event. If the view has a mouse 
down handler it will respond to the event, if not, each successive enclosing view gets a chance to respond 
to the event until one some view responds. 
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The Layer Server 


The desktop is managed by the layer server, a system service that subdivides screen real estate into 
layers. Each layer is owned by an application. Your application may decide to place every window ina 
separate layer, or place multiple windows in a single layer (a la MultiFinder). The default behavior for 
Pink will be to place every window ina separate layer and use another mechanism to allow the user to 
group windows into logical projects or rooms (to use Xerox’s term). [The layer server would need to be 
extended to support grouping.] 


The layer server model has been designed to support a multi-processor system — all screen real estate 
changes must be made through the layer server. Update events that are caused by inter-layer changes are 
the responsibility of the layer server and are transmitted to an application through the event server, just 
like other external event such as mouse and keyboard events. Intra-layer view updates are handled by 
the view system within your application’s address space, and local update events are posted to the event 
queue. You as an application writer will never r have to deal with update events from either the ele 


server or view system directly;: 
called. 


Currently the layer switc 
change to allow the proteca 
switches to occur on mouse up ‘ viding a desktop class 
which wraps up layer f 


The Respon 


The responder chai 
can’t, or doesn’t wa i 
to handle the event, the appli E recei may 
either respond to or ignore the event. : 


Every object in the responder chain must de 
has a dictionary specifying the events to whic 
to an event, it looks in its dictionary, and the dic u 
the event. If it understands the event the handk i Q il fe event 


The first object ta. 
positional, it goes” 
target points to doesn’t 


nrevent depends on t 


t non- 
pplication i is signals for setting tt 


If the event is a positional event, the application framework uses the visual hierarchy to pass the event to 
the view in which the event occurred. If that view does not want to handle the event, every enclosing 
view is given a chance at the event until either some view responds to the event, or no view responds. If 
no view responds the application object does not get a chance to respond to the event [should it?]. 


If the event is responder specific, the event is delivered directly to a particular responder regardless of 
either the target, or if the event is positional, the view the event occured in. The object that is the specific 
target of the event may decide to either respond to the event, or pass the event to its next responder. 


In the following diagram the target points to a view whose next responder is a document. If the view 
can’t handle the event, e.g. a mouse down, it passes the event to the document. If the document can’t 
handle the event it gets passed to the application. 
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The default behavior fo 
next responder for the \ 
This could have been ei 
the event, or because 


mder is its enclosing vi 
et is not its enclosing vi 
n’t want any of the int 
e are sO many intervening views that perf 


above diagram the 
ther the document. 
ws to get a chance at 
‘problem. 


Events 


An event is a just A i vent as 
we know it in the: 


input devices external to your application, é 
to respond to an event, its Respond (TEvent: : m 
dynamically estermunes the event handler fun 


assume that it 


data calls to the: ryou to check the data typ 


e the control of standard interface objects. Fo 
calling the window’s Close () method directly, the close box sends the event “Close” to its next 
responder. No matter how many levels of responder the close box actually is from the window, the 
window will eventually receive the “Close” event, and close itself. All user interface components will 
respond to well documented events so that it will be possible to wire together the interface using a NeXT 
like interface construction kit. When designing your application you should consider where the use of 
events can help make a component reusable, thereby making your application more extensible. 


Another use of events is for synchronization within your own application. If you have multiple threads 
that want to perform actions on the same object, instead of wrapping that object in semaphores you can 
post an event to yourself and be guaranteed that the event will be distributed in the application 
framework’s main thread. 


Flow of Control 
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The standard flow of an event from an input device to the correct responder in your program is shown in 
the following diagram. 


Your application object Gist) 
event Event 


PostEvent (event) Receiver 


Server 
Task Keyboard 
check "ignore 
event" list 


Event'Queue ~ 


Let’s review the sequence of events. First the 
such as the mouse or keyboard. This event is s 
server, decides to which application to send th 


application’s even ver task, which posts % 

ignore event lis } icati blocks 
until the event gq i ecks it 
against the expr : pressed interest in @ whi € i event, 


the event is sent bai rismogrification. If the event px terest check, 
any objects that have registered as event filters are given first crack at the even most common, and 
typically only, event filter is the application menu bar which looks at every event to check for menu 
commands. All events that were not used by a filter are sent to the surrogate that created the event, 
allowing that surrogate to distribute the event as it wants. Most surrogates will just use the default logic 
— positional events are sent to the view in which they occured, non-positional events use the target, and 
responder specific events are sent to the indicated responder. 


Event distribution is guaranteed to be synchronous, i.e. the application framework always distributes 
events in its main thread. 


The application framework gives synchronous control to your application under two other conditions — 
when you are tracking, and when you have requested idler time. If your application is tracking an input 
device, like the mouse, you are given time periodically (at a frequency of your choosing), until the 
tracking completes. The tracking framework allows for tracking multiple input devices simultaneously, 
and for distributing events while tracking is occuring. Tracking time is given synchronously rather than 
asynchronously because it would be very difficult, if not impossible, for you to properly synchronize 
multiple devices tracking, or to handle eventsasynchronously while tracking. Idler time is given only 
when your application has been idle for a short amount of time, i.e. no events have been distributed, and 
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no tracking is occurring. 


Event Distribution 


As described in the “Flow Of Control” section, above, there are three types of events, positional, non- 
positional, and responder specific events. The application framework takes care of getting these events 
to the proper responders — positional events go to view that they occurred in, non-positional events go 
to the target, and responder specific events go to the indicated responder. 


It is possible to bind a particular input device directly to a responder by using the . 
TInputDevice: :SetSpecificTarget () method, such that all events created by that device go 
directly to that responder. This should only be done in circumstances where the user cannot possibly 
become confused. A game is one example, where multiple mice or keyboards are view specific. Another 
example might be the use of a DataGlove, where all input from the glove is directed to the window with 
the architectural drawing, thereby.allowing the user.to. manipulate the scene even though the window i is 
not front-most. 


[Need device binding ats 


“Systérnis to allow new even 
ways this is accomplished. One is by using s 
ws a completely unbounded name space fof 

distribution. New devices might: 
re in — to the target, to the 


The primary goal of the event distribution: 
handled. There are twa'¥ 
mask. Using strings 
all events to their surF 
criteria other than t 
responder. 


w devices to be properly 
vents, rather than a bit 

ie other way is by routing 
ribute their events based on 
der specific, or binding to a 
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Graphic Application 


Architecture 


Every graphical program must create a subclass of TGraphicApplication and create only one instance of 
this class. The application is the highest level in the responder chain. It is the only responder without a 
next responder. 


The application thread is one the main thread, and while this is preferred, it is not required. The 
application object instantiates several supporting objects, including the event queue, tracker and idler 
queues, source manager, and application menu bar, anone with one light-weight thread, the event 

receiver task. 


“with MacApp 
of programming. 
e you write the 


The motto of the applica 
or Think’s object-oriente 
If you are more comfort, 
main event loop, and co: 


me, I'll call you.” If ite 


ine to rewrite youl 


uter platform. To do so 
requires that the eve fi - 


MainEvent Loop 


‘Once started, the application goes into it is pla vent 
queue. Each event is removed and distribu } 
deleted!, and the application blocks until anot ¢ : 
distributing events, the main event loop gives ‘ icati : ora 

short amount of time to pee in the idl i : 


Trackers are giv e.USe 
multiple trackers { 01 iple i “”— in that 
case each tracker is gi : i ing, i ing € wil ibuted and 
processed?. [Note: the synchronization of events that affect objects that are being tracked 


Any responder in your application can request that it be given periodic time when the system has been 
idle for a small amount of time. The application framework senses when the system has blocked for a 
small amount of time—i.e., no events have been distributed, and no trackers have been given time—and 
looks in the idler queue to see if there are any idlers?. 


Le To keep a reference to an event you must call the event’s Clone () method, you must not keep 
a ptr to it since the application framework deletes each event after it has been distributed. See the chapter 
“222” for more information. 

2, This works now, but we have yet to see whether this is something that is both useful and 
understandable. It may be disconcerting to have certain events distributed during tracking, e.g. closing a 
window with a keyboard command at the same time that you are dragging the window. 

os It is possible to supply behavior equivalent to the idler queue by creating a thread, but threads 
require synchronization, and it is often useful to be able to get time synchronously, when you can be sure 
that no events are being distributed. Consider blinking the text cursor—if the blinking is handled asa 
separate thread, it is necessary to synchronize the blinking with incoming keystrokes, using semaphores, 
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Application State 

When an application is launched it may or may not require an interface. For example, the Finder might 
launch an application just to perform text retrieval, to make a print request , or to grab data from a link. 
In these cases there is no need for an interface. 


{I don’t know what's going to happen here yet, but I know it should be something ...] 


Priorities 


brought to the front, the p 
interface has the highest p 
pre-specified categories, $ 
Wrappers” documentati 


n application are assigned to 
ive, and server categories 


Class Diagr 


See first page of this 


Usage 


TGraphicA pplication must be overridd 
An application usually has one or more docu 
you to create documents, there is no documer 
that there will be in the future). 


t of the responder ch , ] 
fic — each event:will ) iin. If 
-it will end uf i 


The application i 
positional, or re 
no responder hi 
event, the messag 


Writing the main program 


In your C++ main () function, you must first instantiate an application object. After instantiation you tell 
the application to start running by calling its Start () (a method of MMessageTask). 


main () 
{ 


// Create application object, and start it running 


TMyApplication app(); // see header file for any parameters 
app.Start(); // method of MMessageTask () 


so that, for example, the cursor positioning code doesn’t interfere with the character insertion code. 
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// If we get here then the user has quit the app. 


return 0; // for C runtime clean-up 


Your application object 


Your application object will be a subclass of TGraphicApplication’, and will look something like this: 


TMyApplication :: TGraphicApplication { 
protected: 
virtual void Main(TMemory &); 


public: 
TMyApplic: 
virtues 
virtual : About ToQuit () ; 


ie 


void TMyApplica 


This is a method of } 
never override Start C°% 
constructor, but before your application 
background tasks, or installing responders: 
call the inherited Main (). 


‘ the applic : i must 


void TMyApplication: :AboutToQuit () 


Upon exiting from't! 
perform any nec 


event loop, the apr on framewo 
p at this time. 


Methods You ant To Ovside 


void TGraphicApplication: :BecomeActiveApp () 


If you want to be notified when your application becomes active, or front-most, you should override this 
method. You must call the inherited BecomeActiveApp (). 


void TGraphicApplication: :ResignActiveApp () 


If you want to be notified when your application becomes inactive, or no longer front-most, you should 
override this method. You must call the inherited ResignActiveApp (). 


4, Applications that do not need a user interface, e.g. pure servers, may descend from 
TApplication instead. 


$$$ 
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Methods You May Want To Call 


void TGraphicApplication: :RegisterEventFilter(MEventFilter *); 


Objects, like the menu bar, that want to get first crack at each event before it is distributed, may register 
as an event filter. After each event is pulled off the event queue, but before it is distributed, all registered 


MEventFilter’s are passed the event by calling MEventFilter: :CheckForCommand(). The menu bar 
gets first crack, and all other MEventFilter’s are given a chance in the order in which they were registered. 


If any of the calls to MEventFilter: :CheckForCommand() return TRUE, no other MEventFilter’s.are 
checked and the event is not distributed. - 


void TGraphicApplication: :UnregisterEventFilter(MEventFilter *); 


The opposite of Registerk 


static TGraphicApp lication: :GetRunn! 
const; 


This method allows any:6bject in your application to get a pointer t 


static TSourc ication: :Get: 


This static member ; icat i °) nager 
object. 


static TEventQueue* TGraphicApp 


This static member function allows any object 
object. 


static TWin 


This static membé robye ator tothe: dow list for 
all windows that resi e isa le for you to 


af & 
manipulate the window list — ~ you must use the view system to manipulate the window list. 


This iterator is protected by a semaphore so that the window list will not be changed while you iterate. 
You must hold the iterator for as short a time as possible since all view changes are blocked until you 
delete the iterator. Additionally, only one iterator is available at a time so I don’t have to go through 


semaphore machinations, you will receive a NIL iterator if one is already outstanding. 
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Event, Tracker and Idler Queues 


Architecture 


Events may be placed in the event queue from either an external source, such as an input device, or any 
object within your application. External events come via the event server, and are posted to the event 


queue by the event receiver task which calls TEvent Queue: :PostEvent (). If your application wishes 
to post an event to itself, it may use either TEventQueue: :PostEvent (),0r 

TEventQueue: :PostEventTo(). If you wish to post an event to another application you may use 
TEventQueue: :PostEs AE 2 


rom any thread. 
élivered, unless the 
positional, or responder 


All calls to the event qu 
The event queue is of ¥ 
application quits with 
specific, and are deli 


shores, so they can be calle 
all events are guaranteet 


in timestamp oraer. 


+methods IgnoreEvent () 
osted to the event queue. 
ceyDown” are 
eptEvent (). 


It is possible to ask. 


and AcceptEve 
The application f 
ignored. If your; 


event queue to filter out unwanted events: 


There are two ot! 
objects are placed on the tr x 
drag the window for example. Object: 
“MouseMoved” events. Every time one: 


Events, tracker ce: 
means that synchronization : 
track continue time, or when an idler gets time. 


Class Diagram 


See first page of this chapter. 


ir a el ee er 
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Usage 
Event Queue 


The event queue is instantiated by the application framework, you never create one. You may geta 
pointer to the event queue by calling TGraphicApplication: :GetEvent Queue (),a static member 
function of TGraphicApplication. Events that are received from the event server are automatically placed 
in the event queue by the event receiver task which calls TEvent Queue: :PostEvent (). All event 
queue calls are protected by semaphores, so you can call them at any time, from any task. 

You may post an event to yourself using either PostEvent () or PostEventTo(),or to another 


application using PostEventToApp(). There are several calls allowing you to peek at and get the next 
event. 


There are two event ownershi 
of the various peek and ge 
event system are owned 6 


pointer or other referenc 


event, you Clone () it., 


Tracker Queue . 


To place a tracker in 
method. The tracke 


TTracker: :GetP 


TTrackerPhase$ 
from the tracker queue (ther 


tzeue you instantiate a tracker, rtTracker () 


ts Sta 
by..callin 


Idler Queue 


To place a responder in the idler queue, you c 
parameters to InstallAsIdler() — the fr 
responder when: time is given. This allo 
once for each se idlers only 
idle messages 

message “seco 
be received, after th 


ett idle for a small amount of time. feet 


Methods you may want to override 


You cannot override the event queue, and the tracker and idler queues are inaccessible, so you’re out of 
luck here. 
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Methods you may want to call 


Event Queue 
You may want to call a lot of the methods in TEventQueue. Refer to the 411 documentation for details. 
Tracker Queue and Idler Queue 


Neither class is accessible. You add a tracker to the tracker queue by calling its Start Tracking ( ‘ 
method. You add a responder to the idler queue by calling its InstallAsIdler () method. 


Cee ee a ee a a te a 
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Events 


Architecture 


Events are strings —- the mouse creates “MouseUp”, “MouseDown” and “MouseMoved” events, the 
keyboard creates “KeyUp”, “KeyDown”, “AutoKey”, “ModKeyUp” and “ModKeyDown” events. _ 
Strings are used to allow for an unbounded name space, since new input devices may require more event 
names than we can possibly reserve in a bitmask. 


Using strings for events has two useful side affects. One, events can come from user scripts as well as 
input devices, since most responders respond to events regardless of which device created it. Two, the 
user interface components with one another, allowing for runti 1g of 
the interface, and the buil mponents : 


Ositional events use 
ire sent to the target, 


There are three kinds of 
the view system to deter 
and responder specific eve 


tional, and responder 
e event, non-positio: 
dicated responder, 


n the Blue world are a subclass of event 
with information about the device that: 


Events as we know the 
normal event string 


vents, that include the 


There are two event; hat you remove ff 


of the various get e 
system are Owned’ ast never dele 


Class Diagram 


See first page of this chapter. 


Usage 


Important See the eve rules in the architecture section ab 
You may create your own events at any time, and either send them directly to the responder chain by 
calling any responder’s Respond () method, or post them your application’s event queue using 


PostEvent () or PostEventTo (), or post them to another application using PostEventToApp (). 


Posting an event to yourself is a useful method of synchronization. Any thread can post an event, and 
then the application framework will distribute the events synchronously, in the framework’s main thread. 


There are several TEvent subclasses that you may find useful — TEventWithBoolean, TEventWithLong, 
TEventWithPoint, TEventWithEvent. These allow you to package an event with another value that you 
can then send. For example, the event “MoveTo” requires a point, so you would create a 
TEventWithPoint, and “DragSelf” requires a mouse event, so you would create a TEventWithEvent. 


Methods you may want to override 
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You will rarely subclass from the event classes unless you are writing your own source, e.g. a driver for a 
new input device. In that case you should subclass from whatever event most closely resembles the event 
that your device produces. For example, if you have a new type of keyboard, that adds pressure 
information, then you might subclass from TKeyEvent. If you have a DataGlove, you may either subclass _ . 
from TMouseEvent because your events are also positional, or you may instead want to subclass directly 
from TPositionalEvent (you may in fact want to create an abstract class T3DPositionalEvent that 
subclasses from TPositionalEvent). 


Methods you may want to call 


This is completely event specific. See the 411 documentation for details. 
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Devices and the Device Manager 


Architecture 


The design of devices and the device manager allows new and unusual input devices, both physical and 
logical, to be easily designed, automatically attached, and immediately usable by every application. See 
the paper “A Design for Supporting New Input Devices” by Michael Chen and Frank Leahy for 
background information. 


The device manager contains references to all devices that are attached to the system. You can query the 
device manager to see what devices are attached, and get a pointer to a particular device based on its 
class and name. 


sréss interest list 
e event is sent 
tribution of events 
‘they would be 
following device 

our application will get 


The device manager keeps ore an event is distributed 
is checked, and if no one 
back for transmogrificati 
for which no one has e 
dropped on the floora 
classes at startup time: 


mouse and keyboard 


devices, such asa p : 
though the original paint program 
in the new device by calling TDevice 
whereby the application will be distribute t 
calls TDeviceManager: :RemovelInterest 
revert to being transmogrified rather than distr r 


There are two itional an iti ically or 
logically attach 
loaded, or, if the ; 
surrogate that allows the application to access the device from within the a plication address space. 
Typically only the tracker framework will have cause to call device methods, but if you need information 
from a device at other than event time, you can query it directly after getting its surrogate from the device 
manager. 


The following diagram, taken from a previous section, shows the use of surrogate devices. The 
surrogates are given the events created by their “real” devices, and they distribute them. The default 
logic is that positional events use the view hierarchy, non-positional events use the target, and responder 
specific events go to the indicated responder. It is impossible to predict what types of new input devices 
and events will appear, and how they should be distributed in an application, we have designed the 
event distribution mechanism to let the surrogate device decide how to distribute its events. 
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Your application object | Crouse) 
Event 


PostEvent (event S 
erver 
Keyboard 
check “ignore 
event" list 


Event'Queue 


Each device has two pieces of infortrag 
categorize devices, e.g. mouse, keyboard;'s 
devices when more than one of the same cl 


Every device has a modifier keys keyboard ass¢ 
modifier keys passed with the event are those 
important when multiple keyboards are attach 


Class Dia 


See first page of this chapter. 


Usage 


Device Manager 


Functions provided by the device manager are — attaching and detaching devices, setting the system 


target, expressing and removing interest in a device class. 5 


The application framework handles attaching and detaching devices and setting the system target, you 
should have no reason to intercept or override these functions. 


The application framework expresses interest in the two ubiquitous devices — the mouse and the 
keyboard — so you don’t have to. If you want to get events from other devices you have to specifically 


express interest in those devices. Any object in your application may call ExpressInterest () or 
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RemoveInterest () to express or remove interest in a particular device, so that your application 

does /does not receive it’s events. If your application does not express interest in a particular device, all 
of its events will be transmogrified before your application receives them. If the device can’t 
transmogrify its events the events will not be distributed; this is done so you don’t get flooded with 
events from new devices that your application doesn’t support. 


Other than expressing interest, you should never have to query the device manager directly. Whenever 
an event needs to be distributed the application framework handles all calls to the device ma nager. I[f 
you are writing a program that wants to track the mouse at all times, even when the mouse is up (e.g. 
Jack Palevich’s program Neko), you could find the primary mouse by calling 
TGraphicApplication: :GetDeviceManager ()->IsAttached (TToken (“Mouse”), 3 
TToken (“Primary”) ); 


Devices 


You will rarely have causé 
distribution time is hand. 
during tracking (a call to 


; directly. All device interaction-at 
ork, and communication t 
#)) is handled by the trag 


‘evice needed 


None, since you ca 
override anything 
Devices 


The following methods are described for peop! 
logical device. It isn’t possible to change the bi 


void TDevice::Di 


If you want tod te yet device i 3 s0sitional 
and non-positiona verride this method. s 


The standard non-positional distribution method is as follows: 
1. If the event is NIL, don’t distribute anything. 
2. Call GetBoundTracker () to see if the device is currently tracking. If it is tracking, call 


theTracker~>HandleEvent (event) to give the tracker the event. This allows the tracker to 
get the event immediately, rather than having to wait until the next time the tracker is scheduled. 
3. If the device is not tracking, see if this is a responder specific event by calling 


GetDistributeEventTo (). Ifa specific responder has been defined distribute the event to it. 
4. If there is no specific responder, see if there is a specific target for the device by calling 


GetSpecificTarget (). If there is a specific target distribute the event to it. 

5. If there is no specific target, get the standard target by calling GetStandardTarget (). 
Get StandardTarget () uses the system target, getting it by calling 
TDeviceManager: :GetTarget (). 


6. Once a target has been determined, call target->Respond(event, TRUE). This call returnsa 
Boolean indicating whether anyone responded to the event. 
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7. If the event is not responded to by the target, call TransmogrifyEvent (event), asking the 
device to transmogrify the event. If the event is transmogrified call 


target->Respond(transmogrifiedEvent, TRUE). Keep transmogrifying the event until 
either the event cannot be transmogrified, or until someone responds. 


The standard positional distribution method is the same as for non-positional events, except for steps 4 


and 5. In step 4, GetStandardTarget () uses the layer id in the positional event to determine which 
layer’s view hierarchy to begin traversing. If there is no layer id, it uses the window list to determine 


which window the event was under. Instep5, target->RespondPositionally (event, TRUE) is 
called instead of Respond(event, TRUE). ‘ 


void TDevice:UpdateEvent (TEvent &) 


This only needs to be overridden if the device produces trackable events. For example, the keyboard 
does not produce trackable to override this method. 


event. The data 
7ént’s cursor location 


Given a reference to its ev 
that needs to be update 
field. 


hatever is necessary to u: 


An interesting side-af 
device directly, is that 
example where the s done by having Control- 

Down4Arrow create Upevent. In between 


the two events, the J in E ethod. | 


fing trackers to query the 
to very easily create 


overrode that met osition 
depending on the state:of 


TGPoint TPositionalDevice: :Get 


Override this only if the device is a subclass O 
device’s cursor location in global coordinates. 


TEvent* TD 


Attempt to transmdg: 
event can be transmogrified, perform the uisicrenley faye either in ike g anew event. 
Call TEvent : : SetDeviceClassIsActingLike () to set the correct device Ae for the newly 
transmogrified event. 


Return the transmogrified event as the return value. This allows you to either modify the original event, 
or to create a new event to be returned. 


void TDevice: :AppDidActivate () 


After the application becomes the front app, it calls this method for every device in the device manager. 
Override this method if your device needs to know that the application was activated. You do not need 
to call the inherited method. 


void TDevice: :AppDidDeactive () 
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After the application resigns as the front app, it calls this method for every device in the device manager. 
Override this method if your device needs to know that the application was deactivated. You do not 
need to call the inherited method. 


Boolean TDevice: :IsUserVisible() 


Some day, some how, some one, will write a desk accessory to display the names of the input devices 
attached to the system, and let you change them. Obviously only those devices that are user visible 
should be displayed. 


Methods You May Want To Call 


Device Manager 


TDevice* TDeviceMa Hist TToken 


&deviceName) cons 


ist TToken &deviceCla: 


See if there is a device 
if there isn’t. 


tif there is, return NIL 


TDevice* TDeviceé 


See if device is sti 


Boolean TDeviceManage: 
See is there are any devices of class d 


Boolean TDeviceManager: :AnyAttac t) 
const; 


See if there are an. 


ned(const TToken &d F evices) 
const; 


Return in devices all devices that match the class deviceClass. 


void TDeviceManager: :GetAllAttached(const TProperties &withThisPropertyList, 
TSet &devices) const; 


Return in devices all devices that satisfy all of the properties in the property sheet 
withThisPropertyList. *** Currently unimplemented. 
Devices 


See the individual device for methods you may be interested in. 
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Writing New Device Objects 


The simplest device is TLayerDevice, the logical device used by the layer server to distribute layer update 
events. You should look at this code first, and then the mouse and keyboard code for more information. 
Trust me, it’s easy. 


There are three pieces of code that need to be written before a new physical input device can be attached 
to an application. One, the ISR, or Interrupt Service Routine, is a small stub of C or assembly code that 
passes information to the Access Manager. Two, the AccessManager is a C++ object that does not run at 
interrupt time, but when combined with the ISR is equivalent to a device driver on the Macintosh. 
Writing an ISR and Access Manager is completely out of my league, and personally I’d be appalled if I 
ever had to get anywhere near that stuff. See the Opus Spec for writing such things. 


The third piece of code, the device surrogate object, which descends from TInputDevice, exists in the 

application’s address space, and insulates the app anon framework from having to talk to the Eis or 
Access Manager directly. This:device:surroga 
layer device, or the Finder 
which of the devices the d 


Distribute (), Updated (), and operator>> ator<<=, Sadar 
is a positional event, Ge Pee eT Ss. : 
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Responders 


Architecture 


MResponder is an abstract class that implements the ability to receive and handle events. Any object in 
your application that responds to events from either within or without your application should descend 
from MResponder. You generally won’t need to subclass from MResponder directly because most of the 
classes that you will want to subclass from are already subclasses of MResponder. 


Caveat emptor. The responder architecture assumes that you are using it from the main thread of the 

application framework, and is not protected by semaphores to stop you from doing something stupid. Of 
course it is possible to call Resp SR thes: 
application framework thr 
absolutely sure that the hz 
simultaneously, or that yé 
events to yourself, and s 
be safe. 


very useful thing to do, bu 
an not be called by ano 
'y. One way to get arou) 


t yous 


oblem is to post 


MResponder has capa there was talk of 
combining the two fur er really do have 
separate functionality. us requests from objects 
within your applica plicatio t come 
through a synchroni 
receive from events, 
responder can pas u 
responder is that no synchroniza 
guarantee’s that it will only call Respondé 
the responder handler lookup overhead w 


A responder can either respond to an event or ‘ 
whether it wants to respond to a particular ever ing i icti ie pting 
to match the event e with a corresponding entry : : are 
the instance scri: i icti y class 
response diction 
called, the event 
if a match is found: 
method to be called. 


ri 
‘Oa handler 


Because of C++ compile time limitations, every handler function must be of the same type. Every handler 
takes a TEvent * as a parameter. Inside the handler function you must cast the TEvent * parameter to 


whatever object you “know” it is, e.g. toa TMouseEvent * in the mouse down handler. Unfortunately 
without run-time type checking it is impossible to be sure that the stimulus is actually the object that you 
think it is, and so the type cast is unsafe. 


Class Diagram 


See first page of this chapter. 
Usage 


a a 
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There are five macros that you must use when defining a new responder subclass. In your class 
declaration must include the ResponderDeclarationsMacro () like this: 


class TMyClassName : public TMyClassesParentsName { 


ResponderDeclarationsMacro () 


public: 

// your stuff here 
protected: 

// more of your stuff here 
private: 


des // even more of your stuff here 


ES 


seful things 
cted 
declaration after 


This macro declares all o 
various methods and sta 


declarations, you should 
using the macro. 


fass needs, as well as som 


In your code you must : 
ResponderDefini ¢ : | ions . The 

ResponderConstxi . ae: last always be 
used inside of your a. : n $s. would 
look. 


ResponderDefinitionsMac 


TMySubClassName: : TMySubClassNa 
: TMySubClassesParentsName ( 


oleae mae pclae 


The three paramters to the ResponderDefinitionsMacro () are 
¢ your class’s name 
* your superclass’s name — if you are using multiple inheritance then this must be the class that 
descends from MResponder 
e ExecuteMyResponse(stimulus) // this must be typed exactly like this, capitals and all 


The last macro, RegisterResponseMacro () is used to associate handlers with event messages. This 
macro must be used in between the ResponderConstructorBeginMacro() and 


ResponderConst ructorEndMacro() macros. To associate three different handlers with incoming 
events, you would write the following: 


ResponderConstructorBeginMacro () 
RegisterResponseMacro(TWindow, “MouseDown”, HandleMouseDown) 
RegisterResponseMacro (TWindow, “Close”, HandleClose) 
RegisterResponseMacro (TWindow, “Zoom”, HandleZoom) 
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ResponderConstructorEndMacro () 


The three parameters to RegisterResponseMacro() are 
* your new class’s name 
¢ the string you want to respond to 
¢ the name of the handler function 


The handler function must be a MResponderResponseFn which is defined as 


typedef Boolean (MResponder::* MResponderResponseFn) (TEvent *); 


meaning your handler declarations would look like 


Boolean TMySubClassName: :HandleMouseDown(TEvent *event) ; 
Boolean TMySubClassName: :HandleClose(TEvent *event) ; 
Boolean TMySubCl 23 Event *event); 


When writing a handler fu whatever 


type you “know” it reall : 
TMouseEvent*. In th Event * because the 
original event, a mouse .d6: 3 tWithEvent *. 


they are described in the “Target” 
void MResponder: :WantToBecomeTar 
void MResponder: :WillingToResignTa 
void MRespond acomeTarget () 
void MRespon 


void MResponder?:Di 


void MResponder: :ActivateTarget () 
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Methods You May Want To Call 


See the Usage section for a description of the four responder macros that you must use. 


void MResponder: : IsEnabled () 


Call this to find out if the responder is enabled. If it is disabled it will not respond to any events, nor will 
it pass events on to its next responder. 


void MResponder: :SetResponderName (const TToken &) 7 


It is possible for you to name any or all of your responders. Once named you can look them up by name 
and class. See MResponder: :GetResponderFromClassAndName (). 


Static MResponder* MRe 
&className, const T 


der: :GetRe 


derFromClassAndName (const TToken 


The system maintains a nders. Call this static mest 


MResponder to look for, 


The Responc 


There is a hook in th ¥: time Respo 

called for every respé ] } OW) plement 
the Hook () metho 
other. Of course lo < 
function MResponder: : AddRespori 
MResponder: :RemoveRespondHook 
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Target 


Architecture 


Every layer in your application has its own layer target. When a layer switch occurs, the layer manager 
sets the system target to be equal to the new front layer’s target. Before the layer switch occurs, the _ 
system target is told to deactivate, and the target is temporarily set to the application. After the layer 
switch has occured, the newly front most layer’s target is told to activate, and the system target is set 
equal to it. 


The target is set by calling Set Target () on any view in the layer (it’s a view method). If the layer is 
front most, then the system#argetis:changed: {thedayer is not front most then the target is. stored in 


focus which should onl 
key. 


The target is automati 
common target chan 


method Want ToBec Benet: 


nGvaGHiagEl fanager () ->GetSystemTarc 
the system target, it for you, using the target of the . Youcan only 


set the target of a layer by calling Seta cost () on any view in that layer. The v view system will ensure 
that the system target stays in synch with the layer target. 


Whenever a layer switch occurs the following actions take place: 
¢ System target’s DeactivateTarget () method is called. 
e System target is changed by the view system. 
¢« New system target’s ActivateTarget () method is called. 


You might use this to perform inactive hiliting on text or graphic selections. For example instead of 
hiliting selected text you could put an outline around it to show that it is selected but not active. 


Setting and Getting a Layer’s Target 
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Each layer keeps track of its own target. You can get it by calling Get Target () on any view in the layer, 
and set it by calling Set Target () on any view in the layer. 


The view system changes the target whenever a mouse down (or any target changing event) occurs. 
When such an event occurs the following actions take place (assume that the layer that the view is in is 
already front most): 


e User clicks in a view 

e The view’s Want ToBecomeTarget () method is called 

¢ Ifthe view want's to become the target, call Set Target (this) on the view. 

* SetTarget () calls the current target’s WillingToResignTarget () method. 

¢ Ifthe current target is willing to resign, call the current target’s ResignTarget () method, then 
the new target’s BecomeTarget () method, and finally set the system target. 


The default implementation. fr 


WillingToResignTarg 


ToBecomeTarget () and TRUE fro 
rride these methods in your view’s' 


@ user mouse 
. You should 
.g. a command object, 


It is possible that you w 
down’s. The best place 


override BecomeTarge 
or a Selection object. 


ew to become the targ 
w’s BecomeTarget; 
and set the target to whichever object is apy 


echanism, and move as m 
-as possible.] 


[We need to revisit the 
server and into the a 


the event server and layer 


Methods Yo 


void MResponder: :WantToBecomeT 


Before the target is changed, the new target is: 


behavior is to return FALSE. Override this me 
become the target. You do not have to call the 


me the target: 


See the chapter 6 sét.mechanism for more information. 


Before the target is changed, the old target is first asked if it is willing to resign the target. The default 
behavior is to return TRUE. Override this method if you want to want to do some checking before 
releasing the target. This could be used, for example, to perform edit checking before allowing the target 
to change. You do not have to call the inherited method. 


void MResponder: :BecomeTarget () 


Override this so that your responder object gets informed when it becomes the target. You do not have to 
call the inherited method. 


void MResponder: :ResignTarget () 


Override this so that your responder object gets informed when it is no longer the target. You do not 
have to call the inherited method. 


void MResponder: :DeactivateTarget () 
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Override this method if the responder can be a target, and you want to know when it is deactivated. 
Deactivation occurs when the layer in which the target is placed is no longer the front most layer. You do 
not have to call the inherited method. 


void MResponder: :ActivateTarget () 


Override this method if the responder can be a target, and you want to know when it is activated. 
Activation occurs when the layer in which the target is placed is becomes the front most layer. You do 
not have to call the inherited method. 
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Trackers 


Architecture 


Trackers are objects that receive time while the user is tracking a user interface object. Tracking typically 
involves an input device such as a mouse, but may result from a user script. z 
When an event occurs, the responder that handles the event decides whether tracking is required, and if 
so creates a tracker object. After instantiation, the tracker object is told to StartTracking(), 
whereupon the application framework places the tracker ona tracker queue. Once on the queue the 
tracker receives time synchronously, i.e. within the application framework’s main thread. All trackers on 
ie; either pe LE requency of their choosing, or based:@: nl 
a tracking completion event. |... 


events, like “MouseMoved 


ntil either an event arrF#! 
er trackers meaning 
in event arrives from a device that is current 
‘looks at the event and decides if it is a tra 
a mouse up, the tracker calls its own Tra 


completion event, the 


The application framewo 
until a tracker needs tim 
tracker’s get time. When 
to the tracker. The trac 
completion event, such 


phase to kTrackCom 
method, and returns 


ye event queue, or 
et distributed before 
eked, it is given directly 
ionevent. Ifitisa 
e() method, and sets it 


Ets Own TrackContinue () 


It is possible to hav 
on the tracking freq 3 
Allowing multiple, simultan ; tra 
potential for creating inconsistentcies. 
a command key to close the window, you ri 
currently no framework in place to help you 
about it.] 


a tracker 


completed. 


There are four tracker methods that get called by the tracking framework — TrackFirstTime (), 
TrackFirstContinue(), TrackLastTime(). TrackFirstTime () is called with the originating 
event, and you will probably want to record whatever initial state is important to you. 

TrackCont inue () is the work horse routine, and will get called either periodically, or whenever a still 


tracking event occurs, such as a “MouseMoved” event. TrackLastTime () is called when the tracking 
completion event is received. 


The calls TrackFirstTime() and TrackContinue() both returna tracker. Typically the return value 
is the current tracker, but it is possible to return a different tracker, allowing you the flexibility to switch 
trackers in midstream. This has interesting and powerful consequences. If you are tracking multiple 
objects, say a hierarchical menu, or are connecting blocks together with a wiring tool, each object knows 
how to track itself. You don’t want to try to build the tracking of every possible object into one tracker, it 


a a 
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is much better to pass the tracker “baton” from object to object, allowing each to track itself (polymorphic 
tracking!). To do this requires a tracker passing protocol. Such a protocol is fairly simple, and is 
documented below. 


The tracking framework handles several things for you. First and most importantly, after the call to 
TrackFirstTime() and between each call to TrackContinue (), the framework calls the initiating 


event’s UpdateEvent () method. This forces the device that created the event to update the information 
in the event to the current state, e.g. the current location of the device’s cursor. Your tracker should never 
query the device directly because there is no guarantee that what you want to ask is available. For 
example, it is easy to mimic mouse events with a script or the keyboard, and if you assumed that the 
device that created the “MouseUp” event was a mouse you could cause a run-time error. : 


Another important task that the tracking framework handles is tracking completion. While tracking, all 
events created by the device being tracked are sent directly to the tracker, by calling its HandleEvent () 
method. HandleEvent () decides eet the event should cause tracking to stop. If tracking should 

stop, HandleEvent () cal ith.the completion event, and sets the pha: 


kTrackCompleted. Seeit Feted, the tracker framework wil 
tracker from the tracker qu 


You will rarely subclass 3 adMouseTracker or 


TStdMultiClickMouseT# 


“in its HandleEvent(). It 
it calls TrackContinue() 
and returns. If the ey 3 device from the tracker so 


no further events get 


tracking by returning TRUE from the 
rturn TRUE when the user has clicked ne 


events from other devices (e.g. mouse events ue a DataGlove), and because user scripts will also be able 
to synthesize events, you must be very careful to verify the real type of device before querying it. Asking 
a user script for its cursor location could have runtime consequences. 


The return value from this method isa TTracker*. Typically you will return this. If you want to change 
the tracker, you may return any other tracker. You are responsible for deciding whether to delete the 
current tracker, or whether you should maintain a reference to the current tracker in the new tracker so 
control can be returned quickly rather than having to ask an object to reinstantiate the tracker. 


If you return another tracker, it is your responsibility to determine whether the tracker’s 
TrackerFirstTime() method needs to be called, and if so to call it. 


5. Trackers that are mix-ins to other objects probably shouldn’t be deleted, but those that are 
created on the fly probably should. The method DeleteOnCompletion() returns FALSE by default, if 
your tracker should be deleted upon completion, you should return TRUE. 
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TTracker* TTracker: :TrackContinue(const TEvent &event) 


You must override this method. Unlike MacApp, which has three methods — TrackConstrain(), 


TrackFeedback () and TrackContinue() — here there is only one, TrackContinue(). Many 
people had a hard time deciding how to split their tracking code into the three methods, so we make one 


call, and let you either do all your tracking there, or you can add methods like TrackConstrain() and 
TrackFeedback () if that makes sense in your case. 


You should only query the event parameter for information. Because it is easy for devices to synthesize 
events from other devices (e.g. mouse events by a DataGlove), and because user scripts will also be able 
to synthesize events, you must be very careful to verify the real type of device before querying it. Asking 
a user script for its cursor location could have runtime consequences. 


the tracker, you may retur, 
current tracker, or whethé 
control can be returned 


responsible for deciding whether:te 
erence to the current tracker. 
ask an object to reinstantia 


If you return another t 
TrackerFirstTime | 


void TTracker: :! 


You must override 
example, if you aré 
and only stop when a “Mouset 
this method. 


After TrackLastTime () is called, the phas 


is removed from the tracker queue. If the trac 
then the tracker will be deleted. 


void TTracke 


If you are subcla: racker or TStdMultiClickMous 


override thismethod. 

This method is called whenever an event from the device being tracked is distributed from the event 
queue. You should look at the event name, and decide if this is a tracking continue event or a tracking 
completion event. Your code should look something like this: 


void TStdMouseTracker: :HandleEvent (const TEvent é&event) 
t 
static TToken eventCompletionName (“MouseUp”) ; 
static TToken eventContinueName (“MouseMoved”) ; 


TToken eventName; 
event .GetString (eventName) ; 
if (eventName == eventCompletionName) 
{ é 
// Stop the tracking 
TrackLastTime (event) ; 


« Registered/Restricted Application Framework March 15, 1990 2.2.1 ~ 32 


// Unbind the source here so that no more events get sent here. 
event .GetSource() ->UnbindTracker (this) ; 


// This tells the tracker queue that it should remove the tracker 
// from the queue rather than giving it any more time. 
SetPhase (kTrackCompleted) ; 

} 

else if (eventName == eventContinueName) 

{ 
// Keep tracking on MouseMoved event 
TrackContinue (event) ; 

} 

else 

{ 


qprintf (“ r::HandleEvent got ane 


eventNam 
qprintf ¢ 


Methods Y 


Call this when you want t 5 
or whenever a tracking continue even 


This sets the view the tracker is currently tracking in. This should only be set by the tracker. 


void TTracker: :GetFrequency(TTime &time) const; 


This gets the current tracker frequency. This method has no meaning for trackers that are based on 
tracking continue events such as the TStdMouseTracker. 


void TTracker: :SetFrequency (const TTime &time); 


This changes the tracking frequency after the next time the tracker gets time. Of course this method has 
no meaning for trackers that are based on tracking continue events such as the TStdMouseTracker. 
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TrackPhase TTracker::GetPhase() const; 
There is really no reason to ever call this since you know the phase by which tracker method is called, 


TrackFirstTime(), TrackContinue() or TrackLastTime(). The tracking framework calls this to see if the 
tracker should be placed back on the tracking queue. 


void TTracker: :SetPhase(TrachPhase phase) ; 


This should only be called inside HandleEvent(). Calling it at any other time could have interesting 
consequences. 


Tracker Passing Protocol 


There are several situations where.you.will.want.to.track among a group of two or more obje 
Examples include hierarchi age view, or blocks being connect 
wiring tool. : i 


You will need to create a; 
framework, but could beifa‘comimon'protocofis observed. A descript protocols is the best 
way to explain how this. 


When a tracker is cha 
want to keep a pointe 
having to ask that it b 
called. You should 
a very good solutior 


+ future time, rather than 
sthod is not 


ichanged, the new t 
, sary. [Not 


-ourself, inside 


Hierarchical Menus 


When a mouse down occurs in the menu bar, 
menu title, at which time a menu is dropped. A. 
bar’s TrackCont inue () method asks the drop 
TakeTracker ().iethad.. The drop down mer 
menu, returns a 3 ,and 
tracking continu ice th. { insi rdown 
menu, it is the ment tself. This allows new miet “he ' down 
menus without having bar’s tracking methods. 


enu 


If the drop down menu has an item with a hierarchical item, it would display the hierarchical menu when 
the item was selected. As soon as the mouse leaves the drop down menu, it first calls the hierarchical 


menu’s TakeTracker () method, and if that returns NIL, calls the menu bar’s TakeTracker () method. 


It continues to call the TakeTracker() methods until either one of them returns a tracker (indicating 
that the mouse entered that menu), or the mouse goes back into the menu. 


Multi-Column Page Views 


Mouse down ina view which creates a tracker, and start it tracking. If the tracker leaves the view, ask the 
super view to TakeTracker (). The super view is presumably some kind of page view, which has 


pointers to all columns on the page. The page view asks each column to TakeTracker (). If none of 
them respond then the mouse must be either off the page [auto scroll?] or in between the columns. As 


soon as the mouse enters one of the columns it returns a tracker from the TakeTracker () call, which 
becomes the new tracker. 


So a SR i he 
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Connecting Blocks with a Wiring Tool 


Same as for a multi-column page view. Start tracking with the first block, then when the mouse leaves 
the block ask the super view to TakeTracker (). The super view will in turns call each of the other 


block’s TakeTracker() method. When one of them returns a tracker you know the mouse has entered 
it and you can continue tracking with it 
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Views 


Architecture 


Content 


Title Bar 


Content View 


The View System de¢ 
Each view acts asa ¥ 
tioned on the scree 


s display into a hie 
.an application ¢ 


Views are like classic Macintosh e 4 

windows in several other aspects, ho arbi e sin- 
gle-level window system. Second, a simple. 
have a structure region, title bar, close box, ¢ 
drawn in (think of it as all content region). Al: 


yh aw, called a layer. Layers are the unit ich the desktop 
is shared between applications under Opus/2. They are managed by the Layer'Server, which is a system 
wide resource. The Layer Server acts as a primitive, single level window manager, allocating screen real 
estate between different layers and different applications (see the “Pink Toolbox Architecture” and 
“Layer Server” documents). There are many possibilities for connecting windows, layers, and applica- 
tions. There could be one or more than one layer per application, and one or more than one window per 
layer. These are policy decisions which do not affect the architecture of the View System or the Layer 
Sérver. The TGraphicA pplication class acts as an interface between the Layer Server and the View 
System, sending and receiving the necessary Opus/2 IPC messages to keep the two coordinated. 


Because of the preemptive nature of Opus/2, there are multiple resources which need to be synchronized 
for concurrent access by competing tasks. These are the View System itself, the layer, and the graphic de- 
vice being drawn on. Although there is at most one view system per Opus/2 team, it still needs to be 
shared among multiple tasks (threads) on that team. In order to protect the developer from having to do 
a lot of explicit concurrency control, the View System may normally only be used from the main thread of 
the application framework (a.k.a. the interface task), the same thread that distributes events, and which 
gives time to trackers and idlers. Any task may draw in a view, but only the interface task can modify 
view attributes, such as size or position, or create and delete views. 


, | 
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Any task other than the interface task which wants to accomplish these ends can do so by posting an 
event to the application’s event queue. The responder which receives the event (which could be a view, 
since views are responders) can make any call it wants, since responders execute in the interface task. 


The layer itself is synchronized separately. The visible region part of the layer information must always 
be up to date to prevent an application from drawing on an incorrect portion of the screen. The interface 
with the Layer Server is carefully controlled inside the View System to prevent an errant application from 
keeping the layer semaphore and locking up the whole system. 


Finally, the Albert graphics system synchronizes access to the frame buffer on a device by device basis; 
the Toolbox is not involved. 


Usage 
Types of Views 


The primitive view syste Port. There are also ma 


e TTransformer’ S 
zooming and rotation. 


e MPrintable is a mixin class which allo 


Drawing into Views 


@ first is to draw‘ 
lf (TViewPort 
decide to respon wSelf() routine, you must 
approach is suitable eed for animation or to draw asyn 
well when drawing is a lengthy process, as that would tie up the interface task, freezing the user interface 
while drawing takes place. 


There are two op 


wing ina view. 
received; this i 


The other option is to allocate a TViewPort into which you may draw asynchronously. A view port isa 
descendant of the TGrafPort class defined by Albert. Every view port is associated with exactly one view 
and exactly one task. A view can have many viewports associated with it, however, and a task can also 
have multiple viewports at once. Once the view port is allocated, the owning task can draw in the view 


whenever it wants, although the developer must synchronize simultaneous drawing to the same view. 
[222] 


The view port can be used either for animation or to process updates in background. The latter is accom- 


plished by overriding TView: :RefreshInterior() to return FALSE, which indicates that the update 
was not performed synchronously. When the application is ready to start processing the update (e.g. 


after creating the task to perform the update), it calls the view port’s BeginUpdate () method; when 
drawing is completed, EndUpdate () must be called. 
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Building View Hierarchies 


When designing the contents of a window it is useful to break the window down into logical 
subdivisions. For instance in a page layout program, or word processor, there are columns and pictures 
along with user interface controls such as scroll bars. Ina dialog box there are areas with editable text, 
areas of scrolling items, areas of static pictures and text, and user interface items such as check boxes and 
buttons. Using the TView class it is possible to match your logical subdivision with a physical 
subdivision. 


The benefits of matching the physical to the logical is that the handler’s for each of the separate items in a 
window can be self-contained. Check boxes can handle their own checking and unchecking. Buttons 
know how to click themselves, text boxes know how to edit the text entered in them, and a dialog box can 
impose an order on top of all of these items, for instance tabbing properly between them. 


There will be cases where you can use the TView class directly, but more likely you will want to subclass 
and implement behavior s In the following sections you will : 

window, menu, editable a1 and other user interface classes:th 
TView. You will need to d ‘lasses to override. 


Unresolved 


There are still some m. These include: 


screen from being corrupted. We ar 


¢ There is no support for color palettes, p 
* Support for animation, off-screen bufferi 


ment all awat clarification of th : 5 ge as 
the Albert s 5 | 


tion mechanisms we have ct 
1ead is acceptable. 


¢ The performa 
measured to ensu 


¢ Support for networked views. 


Class Diagram 


i 
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MPrintable 


TViewPort 


TScroller 


TTransformer 


TSplitter 


TView 


Methods You Ma 


void Refre ackground(TGrafPort *); 
Boolean Refxr elf (TSeed, TGrafPort x); 
void 
void 
void 
Boolean 
void DrawSelf (TGrafPort *); 


void AS 1f(TGrafPort 


Methods You May Call 
Boolean IsVisible() const; 
void Set Visible (); 


MResponder* GetTarget () ; 


void SetTarget (); 

void ContainerToSelf (TGPoint &) const; 
void SelfToContainer(TGPoint &) const 
void GlobalToSelf (TGPoint &); 
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void SelfToGlobal(TGPoint &); 


Boolean Contains (const TGPoint &) const; 

Boolean ContainsInSelf (const TGPoint &) const; 

void GetBoundary(TArea &); 

TGPoint GetLocation() const; 

void SetLocation (const TGPoint &); : 
TGPoint GetSize() const; 

void SetSize(const TGPoint &); 


void 

void 

void 

void s—i‘(i‘i’déiBedimge ee wax 

void 

void 

void RemoveView (TView™ 

void SendToBack(TView *) ; 

void SendBack(TView *); 

TView* 

TView* 

Boolean GetDra 

void SetDrawClipped (Boolean) ; 

//void InvalidateClipped(const TArea &); 
Boolean IsSubView(const TView *); 

TView* FindSubView(const TGPoint &); 
void SubViewMoved(TView *view, const TGPoint soldLoc, const TGPoint 
&newLoc) ; 

void SubViewChangedBoundary (TView *); 


i i i aN a a ee 
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void SubViewChangedVisibility(TView *); 


a 
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Windows 


Architecture 


Windows are views that appear on the Pink desktop. Typically each window appears in a separate mayer: 
but it is possible to place several windows in a single layer. 


Windows know how to drag, grow, and size themselves, responding to a variety of events such as 
“Move”, “Drag”, “Zoom”, and “SetAppearance”. Every window has a title, but need not have a title bar, 
allowing windows to be found by name. 

Each window has a single subyi led the 
window. Inside the conte 
content frame is used by 
border or frame. The co 
into the content frame b 


tent frame — this content frame is owned: by 

view — a view owned by you 
our content view does not:dr 
window, the content vit 


3HtO the window 
ted and inserted 


It is inside the content 
application that requi 
more complex applicé 
view — one of your 
which you will plac 


w that you will place the views used by yor 


n. If you have a simple 
but a ingle view, you can display it in the 


directly. If you havea 


Class Diagram 


See first page of this chapter. 


e Place the Window 
¢ Use the standard title bar or not 

¢ Place the window into one of six layers 

e Place the window either front or back most amongst other windows in the layer 


If you do not place a window ina separate layer, you must place it inside some visible view to make it 
visible. You may either place it directly in an existing layer, or you may place it in any other visible view, 
e.g. another window. 


If you choose not to use the standard title bar, you may either display the window without a title bar, or 
provide your own title bar. 


By default, new window’s are placed in the document layer. Supplied window subclasses, e.g. menus, 
menu bars and windoids will place themselves in their correct layers, so you will typically have no need 
to override the LayerKind a Daraine ter: The kinds of layers in their order of appearance (from top to 
bottom) are: 

' © Menu Bar Layer 
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Menu Layer 

Alert Layer 

Torn-off Menu Layer 
Windoid Layer 
Document Layer 
Desktop Layer 


Methods You Have To Call 


void TWindow: :Init () 


Because of C++ limitations, it is impossible to correctly set up several window parameters correctly until 
after the constructor has been called. After creating a window you must call the Init () method to allow 


the window to properly initialize itself. A window will not become visible until after its Init thod 
has been called. : : : 


Methods Yo Override 


TContentFrame* T i 


Override this to creat ontentFrame. The standard 


content frame uses the parameters borderwidth and borderHeighe to-create a.rectan 
frame. The content 


Remember that th 


void TWindow: :InvalidateBordé 
&newSize) ; 


int 


If you are creating your own special window 
special invalidation as a result of window resiz : 
frame’s size is also changed automatically. In| 3 im e the 

content frame, Su} c the content view. 34 : i mn, SO it 
needs to be inch r.for it to be eras 


Methods You ant To Call 


TContentFrame* TWindow: :GetContentFrame() const; 


This call allows you to get the current content frame. Along with SetContentFrame () itis possible to 
change content frames on the fly (though why you would want to do this is not immediately obvious). 


void TWindow: :SetContentFrame(TContentFrame *contentFrame) ; 
If the new contentFrame is NIL do nothing. If there is a current content frame, all subviews, if any, are 
removed, and added to the new content frame, the current content frame is deleted, and the new 


contentFrame is installed. 


TView* TWindow: :GetContentView() const; 


Get the current content view, if any. The content view is owned by your application. 
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void TWindow: :SetContentView(TView *contentView) ; 


Removes the current content view, if any, from the content frame, a installs the new content View. 
Does not delete the current content view. 


void TWindow: :GetTitle(TText &title) const; 

Return the current title in title. 

void TWindow: :SetTitle(const TText &title) ; 

Set the title to title. 

void TWindow: :SetSizeUsingContentFrame(const TGPoint &contentFrameSize) ; 


Set the size of the window ontent frame to be contentFra 
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Menus 


Architecture 


Menus are just windows that reside in a menu layer. The menu layer is below the menu bar layer, but 
above the alert layer. 


Menus have pre-defined trackers that make it easy for you to specify Pink style menus, both textual and 
graphical. 


FURIE EERE Ee ee 
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Controls 


Architecture 


To be filled in later. 
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CHER ERS: The Next Generation 


Arnold Schaeffer Larry Rosenstein 
x8117 x8123 


Cher is the Document Architecture for 
Pink. Its main goal is to raise the base 
level of Pink applications by enabling 
several new features such as multi-level 
Undo, hypermedia linking, annotations, 
real-time collaboration, and content- 
based retrieval. 


evel support 


al undo, and (4) retrieval, 
Deck extent possible, 
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Introduction 


Cher is the Document Architecture for Pink. Its main goal is to raise the base level of Pink applications by 
enabling several new features such as multi-level Undo, hypermedia linking, annotations, real-time , 
collaboration, and content-based retrieval. 


Most of these features are available in some existing Macintash application. Unfortunately, these are iso- 
lated cases, because there is no system-level support for them.’ This lessens their impact because it re- 
duces the synergy between applications. For example, only a few applications support multi-level Undo, 
so users can’t count on having this feature available. : 


[n addition, the lack of system support for these features limits their implementation. For example, there 
are applications that allow users to annotate static representations (pictures) of any document, but not the 
“live” document itself. The content-based apa caliaaangee have trouble accessi ng the contents of 
document because each application has 86 3 
ment, itis difficult to do 


example.” 


In the Pink system, the 
these features will be st 
collaboration, (2) hyp 


To the extent possible 
does not specify ho 
the low level mecha 


As mentioned above, Cher provides services ir 


eternal undo, and (4) retrieval, content-based. 
C uses. Its main disad ntages are that some applications draw directt 

the Em picmentanon) and the large bandwidth required to transmit all drawing operations from 
one machine to another. 


yetoct é screen (complicating 


Screen sharing is an example of simultaneous, real-time collaboration. Cher provides support for a 
different kind of real-time collaboration. This operates at the level of changes to the document, rather 
than changes to the screen. Potentially, this will be more efficient because the amount of data needed to 
specify a document change is usually less than the amount needed to update the screen. 


Cher does not specify any synchronization between collaborators. One possibility is no synchronization 


1. System 7 does add some support for these features. 


2. Again, System 7 will fix some of these problems. In particular, a retrieval program should be able to send an 
AppleEvent to the Finder and open the found document(s). 


3. Since this form of collaboration is implemented in the graphics system, it is beyond the scope of Cher. Pink will 
probably support screen/window sharing in its graphics system. 
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(“free-for-all”), in which the participants would be able to make changes at any time. The participants 
would be forced to adopt some ad hoc conventions to prevent chaos, but these wouldn’t be imposed by 
the system. 


It is likely, however, that the user interface above Cher will implement some kind of protocol for passing 
control from one user to another. For example, there would be one person who “has the floor” and can 
pass control to another collaborator. 


Alternatively, each user could attempt to acquire a network semaphore when she started to pull downa 
menu or modify the document. This provides synchronization without any explicit user action. __ 

It is also useful to have asynchronous (i.e., non real-time) collaboration. One form of this is the ability to 
annotate a document. Cher provides low-level support for annotations through its linking mechanism 
(described below). 


is for Hypermedi 
H meaning of an an 
tion. An anchor 


changes. For ex 
word, even if the text 


bidirectional connection betwee 
‘but in most cases an anchor idetit 
ers to the same data regar¢ 
a word within a text.bh 


: ticky sick 
the user’s editing 
ways refers to that 


from one end of the link 
rget anchor, scrolling the 
his behavior; 
he document. 


Once the user creates ; 
to the other. In gene 
anchor into view, ani 


k, she can operate upon it. First, the use 


Cher also allows one application to send an 
applications to implement custom features us 
The straightfor: etween 
documents, na‘ 


This isn’t the only 'S 


application features. In these’ ed will be transparent 
to the user. 


For example, Intermedia uses the low-level linking mechanism to implement an annotation facility. The 
user selects a part of the document and chooses Create Annotation. Intermedia creates a link between the 
selection and an annotation document, and transfers the selected part of the document to the annotation. 
The user can modify the annotation to suggest a change to the document. 


If the author decides to incorporate the suggested changes, she can choose the Incorporate Annotation 
command. This simply transfers the proposed change across the link into the document. Neither the au- 
thor nor the annotator is aware that linking is involved. 


4. The design of linking is heavily influenced by the Intermedia project.(Meyrowitz 1986] 


5. If the user changes something within the anchor, then the expected thing happens; the text associated with the 
anchor changes. 


pi ares 
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Another transparent use of linking could be to simulate the functionality of the System 7 Publication 
Manager. Suppose a user wants to incorporate a drawing to a word processor document. She can select 
the drawing and choose the “Publish” command, select a position in the word processor document, and 
choose “Subscribe.”© This would create a link between the drawing and the word processor document. 
The system would attach an attribute to the link to indicate the publish/subscribe nature of the link. 
Note that the existence of the link is invisible to the user. 


Once the link is in place, the system can provide a command that opens the publishing document or any 
subscriber. The system can automatically push the data across the link when the published document 
changes.’ 


This kind of annotation implemented in Intermedia uses separate documents and windows for the anno- 
tations. An alternative is to use a kind of Hel sia note. This is eigen paver for ene and is rails 


that each annotation does § 
notes, then it is easy to co 
port marginal notes, then 


is for Eternal U! 
E only the last ch: 
MacApp, but 


different users. Also, i 
eric part of Pink to pre 


ntends to sup- 
stency. 


This decision has sevé 
doable. For exampl 
though selections ca 
ing the right combinati 


If the system supports only one level of tty 
getting about the last Cut command, for exa 
lection changes. 


With this change comes the added burden of Pp ; 
commands.’ Th cha se it wi ser 
to create hundré 


Another benefit 6 


[ ased reliability. If every com 
to replay those comm 


an application or system crash. 


it is possible 
.e concurrency 


control and recovery classes (Credence) to save command objects in a robust manner. 


Note that Cher maintains a linear list of command objects. This means that undo returns the document to 
some previous state. In theory, it is possible to enhance the undo model to allow the user to selectively 
undo commands (i.e., undo a Cut command but keep all subsequent commands intact). 


The problem is that commands are not independent of one another. A command that copies a shape is 


6. I’m just guessing at the current interface in System 7. 


7. To integrate a Pink application with a System 7 application (running under the Blue Adapter) we would write a 
Pink program that manages the System 7 publication files, and allow the Pink application to link to the publica- 
tion file. 


8. Thanks to Rob Chandhok for pointing this out. 


9. This isn’t the only place where a good navigation mechanism is required. We will also need a way to visualize 
the set of explicit links between documents, for example. 
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dependent on the command that first created the shape. These dependencies would complicate the user 
interface to undo, as well as the underlying implementation. 


The best solution is to integrate the undo and scripting mechanisms, for example to automatically create a 
script of everything that is done. The user can then edit the script to remove arbitrary command, rear- 
range command, etc. and execute the script. This gives users the maximum flexibility and control.'® 


their computers. Local hard disks are getting larger, and there are many CD-ROMs available that 


is for Retrieval, Content-based. Increasingly, users have more and more information available on 
k contain hundreds of megabytes of data. 


It is impossible to browse through this data without some assistance from the system. In the Macintosh, 
the only standard tool is Find File, which located document based on their name. System 7 will provide a 
faster version of this integrated within the Finder. Third party developers now provide tools that go be- 
yond Find File and search for documents based on their content. The linking mechanism provided by 


Cher can be used to naviga mother, but requires that someone ‘pl outsly set 
up the links. 


It is important that thesé 
ments if the user can’t 
cintosh get no system: 
with the appropriate 
index documents wt 


2d into the system. The 
anything with them 'Fhe third party conte 
port in examining the contents of the docu 
plication. Similarly, On Technology had té 
ey-change."! 


point in locating docu- 
‘feval tools on the Ma- 
én opening the document 
engths to automatically 


Cher will provide and querics. 
Although Pink wil a a sant the 
ability to plug in & vork is 


so that the background indexing: 
underlying retrieval technology. 


The framework will provide for automatic, 
volume or changed. A retrieval system is wo 
unreasonable to place this burden on the user: 


ba. generic query fra 


stall a new: 
ront-en 


VWIMNe 


she doesn’t h 


Concepts 


Writing an application that works with Cher requires a slightly different perspective than writing an ex- 
isting Macintosh application. For example, implementing sticky selections generally requires a different 
implementation for low-level data structures. This section describes some of the concepts of Cher, in 
order to give you an understanding of what is involved and how you approach a Pink application vs. a 


10. Of course, the specification of selections in the scripting language must be sufficiently robust to allow this kind 
of editing. Otherwise, the user will have to do more work than just rearranging items in the script. 


11. At least they made the effort to do this. The NeXT requires that the user explicitly index documents in its Digital 
Librarian. 
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MacApp application. 


Models, Views, & Presentations 


Unlike MacApp, Cher defines an architecture for managing a document's data. The architecture doesn’t 
define actual data formats (either in memory or on disk), but rather defines the protocol between various 
objects in the application. 


The principal object is the Model. A model contains the actual data of the document. Most Pink develop- 
ers will create an application-specific model class, although it is likely that Pink will include some stan- 
dard model subclasses. 


model in different vi 


. It should be easy to create new kinds o 
able if a particular vi 


ld be used with different kinds 


The link between the model and view:# tion. efine 
the change protocol between a model an 
col can work. 

1!2 is one in which each ch 


The simplest protoco 
me cases, it might be 


dependent view 
model changes, 


A second functi 
For example, suppos 
view needs to compute th 
ess oe g., the text is sepia in a split window), then the natural place for them is in the orecentation 
object. 


Commands & Document Saving 


Like MacApp, Cher uses the concept of a command object in its framework for Undo. (As described in 
the next section, command objects are also central to the collaboration features of Cher.) 


Unlike MacApp, Cher saves more than just the last command object created. This provides the user with 
the ability to Undo (or Redo) many changes to the document. Given enough disk space, it will be possi- 


12. This is also the only one currently implemented. We probably will implement alternatives in the future. 


13. They can’t be stored in the model, because line breaks are relevant only to the view. Also, there might be other 
views of the text with different margins that require different line breaks. 
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ble to undo back to a blank document. 


In addition to providing multi-level undo, saving “all” command objects enhances application reliability. 
Cher will periodically (in the background) save command objects to disk, using the Pink concurrency 
control and recovery (CCR) facility. The result is that if the application or system crashes, the user 
shouldn’t lose more than the last few commands. The command objects will be part of the user’s docu- 
ment, so the system will automatically “replay” those commands when the document is opened." 


Today, users save document more often then they want, because they are afraid of crashes that would 
lose the entire document. Under Pink, these kinds of saves won’t be nec eset The only time when the 
user needs to save is when she has a complete, new version of the document. 


For the most part, Cher’s multi-level undo doesn’t make implementing command object any more diffi- 
cult. One difference is that applications won’t be able to “get away” with non-undoable commands. 
Many of the current Macintosh applications when it comes to undo. Most will not undo a command oe 
as Find and Change All, beg ving a duplicate of the document. : 
undo command that are “¢ erself (e.g., font change commati 


It isn’t possible to get aw; 
able, then it is possible 
mand if the pasted text 
saved commands, as ap 


nk. For example, if FA Rrange All isn’t undo- 
: #t undo a Paste com- 


; o throw away all the 


Another difference cé et _ Afi i toesn’t immediately change 
the internal data str re changed 
only when the comm : 


Filter command are useful whertthe 
selects an entire graphics document ai 
quires that we save the old fill patterns for 
fected shapes through a “black filter.” Undo 


In an environment Sk supports multi-level u iltering in’ com- 
mand can potenti uire a filter, the syste | 
Accessing the u : 
that command @ 
if it means maki 
data to save space.* 


d, even 
this 


Cher also provides a framework for “long running commands.” These are commands that are likely to 
take a long time and should be run in the background. We don’t expect that the user will be able to make 
additional changes while a command is running, although individual applications can support this if 
they choose to. For the most part, the user will be limited to operations that don’t change the document, 
including scrolling, window resizing, and switching to other applications. 


There are still synchronization issues, however, because refreshing the window may require access to the 
model. Cher maintains a semaphore for each model to control access to it. By default, all command ob- 


14. Applications can take advantage of this facility to speed up saving. It is possible to specify a change limit for a 
document. If the user makes fewer changes than the limit, then Cher will save only the new command objects. If 
the user makes only one change to a document, the document could be saved simply by writing out the new 
command object. 


15. Although, it may be difficult to change peoples’ habits about saving. 
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jects run in a separate task and Cher acquires exclusive access to the model semaphore before running the 
command. Interface-related tasks that require access to the model acquire the semaphore shared. 


This normally forces the interface to block while a command is running; although Pink will allow users to 
switch applications under these circumstances. A command objects can, however, copy data out of the 
model and release the semaphore, which will unblock the user interface. When the command needs to 
store data back into the model it will reacquire the semaphore and make the change. The command ob- 
ject can make multiple small changes to the model so that the user can incrementally see the affects of the 
command." 


Real-time ait cer 


As mentioned earlier, Cher provides.su 
of view, they are working @ 
same machine. All the us 
One user can undo comm 


-time collaboration. From the collaborator 
iltaneously, as if they were sitting if : 
of commands. 


machine of the user who started the coll 
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with another. 


Because comman 
el-independent: 
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£9 another, it is 
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implementation strateg 
en of the selection objects ( 


Selections & Anchors 


The Cher architecture includes the concept of a selection object, which is not part of the MacApp frame- 
work. In MacApp, the concept of a selection is folded into the view class. 


Cher uses selection objects to manipulate data in the document. The result is that most of the standard 


16. Currently, semaphores in Pink are fair with respect to readers and writers. If a reader task acquires a sema phore 
shared and a writer attempts to acquire the semaphore exclusively (and blocks), then subsequent readers will 
also block. This guarantees that the writer will get a chance to makes its change. To properly handle commands, 
however, we need an “unfair” form of semaphore that will give the user interface priority over the background 
command object. 
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editing commands (Copy, Paste, Push Data, etc.) can be implemented to call method of the selection. This 
means that developers don’t have to implement these command objects, but can simply use the classes 
defined in Cher. 


Like command objects, selection objects must be independent of the specific model object to which they 
refer. That’s because selection objects are distributed to each collaborator. Therefore, developers must 
implement selection objects as specifications of the selection, rather than with pointers into the model. 


In the case of a text model, one possible selection specification is a pair of character offsets. In a struc- 
tured graphics model, each shape must be assigned a unique id, and the selection specification is a set of 
unique ids. : 


Anchor objects are very similar to selection objects in that they refer to part of the model. The difference 
is that anchors must be resilient to editing changes, since by definition, an anchor is a sticky selection. An 
anchor object contains a selection object, so it is usually advantageous to make all selection objects sticky, 
and use an instance of the approp: ; the anchor. 


of text selec- 
“haracter offsets 


The implementation of gi 
tions, however, is not. 
must be adjusted. 
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fext before the selection, 
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he anchors would remain 


There are a couple of 
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When the text was c 
the same. 


roaches for implementing text anchors. 
e text. The anchor would be 
Opriate markers would be 


Another approach 
character positions, 
to record the change (e.g., 5 character 
hens would have to correct its charac 


¥ for the text 


st be selec 
copy and 


Some applicatiaa 
“look” for anc 


Linking 


To create a link between two anchors, the user must specify the anchors. The situation is similar to copy- 
ing and pasting data (the user needs to specify a source and destination), so one way to do this is to main- 
tain a kind of “linkboard,” analogous to the clipboard. The Start Link command would create an anchor 
out of the current selection and place the anchor on the linkboard. The Complete Link command would 
also create an anchor, and then create a link between the new anchor and the one on the linkboard. It is 
possible to choose Complete Link several times, in order to create several links that share a common an- 
chor. 


{n Pink we are investigating extensions to the current Macintosh clipboard model. Two of these exten- 
sions are to support more than one item on the clipboard (as in the Scrapbook) and to support more direct 


17. This is the approach used by Intermedia. 
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manipulation (dragging items to the clipboard as an alternative to Copy). We expect that the linking user 
interface will closely match the copy and paste interface. 


It is also possible for an application to create links programmatically: We expect that most of the “inter- 
esting” uses of linking will fall into this category. For example, annotations can be attached to the affect- 
ed parts of the document with links. Scripts can also refer to parts of a document with links. 


There is only one kind of link in Cher. It is bidirectional, and supports both navigation (finding the other 
end of the link) and data transfer. Links also have properties, which applications can use classify links 
and to restrict how links are used. 7 

For example, there could be properties that specify what the user can do witha link. It might be desir- 
able to allow certain users only to pull data from a spreadsheet and not navigate to the spreadsheet or 
push data into it. 


Links that are used to impk 
indicate that the link is pa i ands are enabled. 


ed to import a graph, 
atic representation of 
ced in the word proces- 
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for example, into a wor. 
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sor document. 
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Classes 


This section of the document contains class and member function descriptions. In the interest of keeping 
this document to a manageable size, certain conventions are followed. All classes have virtual 
destructors. If the destructor does anything more than release storage, it is discussed; otherwise, nothing 
is said. Many of the classes have getters and setters which simply do field accesses. These methods are 
listed in the class declaration but are not discussed in detail. 


8 


Unfortunately, class descriptions do not fully describe the connections between all of the objects. 
Example programs, such as TurboPinkDrawlIJ® augment the documentation greatly. 


Entitys 


A TEntityID is a class which provides a name fora finder entity that is capable of responding to at least 
a minimal set of event messages which we will define (including “Launch”). This class will see 

information provided by t lings. For now, entities could be n : 
object or by a unique id v son the volume. This class is.a: 
until the finder provides 


class TEntity£D 
Publics 
TEneLe yi DAL 


F uniqueID, const TText& name); 
virtual co 
virtual lo 


protected: 
virtual void 
virtual void 

ke 


Type Descriptions 


TTypeDescrip psulate informati 


asically, t 


specific type bet at type can be abstract, 


protocol - contains'dz 


For example, suppose we wish to cut a piece of animation from one document to another document. Part 
of the cut and paste process involves negotiating what types each document can understand. A 
document might know how to deal with an object as a baseclass but not know about the derived class. 
For example, suppose there is an abstract baseclass in the system for animation, TAnimation. There 
might also be a class for pictures, TPicture, that everybody knows about. The document containing 
the data might publish a list of type descriptions that looked like: 

TTypeDescription (TToken(“TMyAnimation”), kAbstractOrConcrete) 

TTypeDescription (TToken(“TAnimation”), kAbstractOnly) 


TTypeDescription (TToken(“TPicture”), kConcreteOnly) 
The use of a type when only the abstract baseclass is known usually involves loading code from a shared 
library (see page 13). 


enum TypeKind { kAbstractOnly, kAbstractOrConcrete, kConcreteOnly }; 


pa ie as 
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class TTypeDescription : public MCollectible { 
public: 
TTypeDescription(const TToken&, TypeKind theKind = kConcreteOnly); 


virtual const TToken& GetTypeName() const; 


virtual TypeKind GetTypeKind() const; 

virtual void SetTypeName (const TToken&) ; 

virtual void SetTypeKind(TypeKind theKind = kConcreteOnly) ; 
bi 
Selections 


Before performing an operation on an object or group of objects, the user must select it to distinguish it 
from other objects. This is known as a selection. There are classes in CHER to represent a sele oie 


mixin class, MSelectable¢ ‘ocol that document selections anda 
expected to implement. 


tion, should be used as a. 
applications are creating different kinds of selectis 
application. It is impor 


cts as being specificat 
is as opposed to the selection itself. For example, in a text document, 
would refer to a rang 


0, 155] of characters instead of containing th 
object. 


ported in the 
‘the actual selection 


McumentSelection 
racters in the selection 


MSelectable obje 
paste or using push 
publish this data i 
publishing data in 


ing cut, copy, and 


sor Per anos data: 
types can | 


DISCLAIMER: The selection protoc 
cut/copy/paste of anchors and links. 


MSelectable 


The mixin class, MSelectable, provides mo 
expected to imple his protocol is used 
commands (cu , 


Sare 
AWNLE 


ment all of 


class MSelect 


public: oe Ess 
virtual MCollectible* GetCopyOfData ( 
const TTypeDescription* t = NIL) const; 
virtual void GetTypes (TDeque& theTypes) const; 
virtual void ChoosetType ( 


const TDequeé theChoices, 

TDeque& theChosenTypes) const; 
virtual TDocumentSelection* AcceptData(const TDequeé& theData); 
virtual TDocumentSelection* AcceptData(MCollectible* theData) ; 


virtual MCollectible* GetSelectionDataForUndo() const; 
virtual MCollectible* GetSelectionDataForExchange ( 
const TTypeDescription* t = NIL) const; 
virtual void SetModel (TModel* theModel) ; 
virtual TModel* GetModel() const; 
protected: 
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MSelectable(TModel* theModel = NIL); 
Ey 


MCollectible* MSelectable: :GetCopyOfData ( 

const TTypeDescription* theType) const 
Given a type description object, this method should return a copy of the data described by the selection. 
For example, in a text editor, if the selection is a range of characters, this method will return an object that 
contains those characters (a TText object). If called with NIL, return the data in your native type (it 


called with NIL, it means you are cutting and pasting between the same application or 0H are saving the 
old data for undo.). 
void MSelectable: :GetTypes (TDeque& theTypes) const 
Fill in the supplied deque with a list of type description this selection is capable of publishing its data in. 
You are encouraged to publish in as many types as you can. 


void MSelectable: sears et olin TDeque& theChoices, 


ChosenTypes) const 
ud like to receive data in for, 


. If some 
‘HOice and save a 
€ document home). 


From the deque of choices 
of the choices require th 
“fall back” position in ca 


eData) 
1 the deque is a 


e application owns the 


TDocumentSelectic 
Replace the data specif 


TTypeDescriptio 
storage associated w; 


TDocumentSelec: 
Replace the data sp e in one 


of your application’ s native: oken 
to determine the actual type. The app 


MCollectible* MSelectable::GetSe 
This routine defaults to calling Get CopyO£D. 
method to do smarter things to avoid copyin 
MCollectible > :GetSel 


This routine de EC rf : : ee iti i override 
this method to d 


TDocumentSelection 


The class, TDocument Selection, should be used as a base class when applications are creating classes 
which represent the different kinds of selections supported in the application. 


class TDocumentSelection : public MCollectible, public MSelectable { 
public: 
virtual TAnchor* Stickify () const? 
virtual TDocumentSelection* Duplicate() const; 


protected: 


TDocumentSelection(); 
Ss 
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TAnchor*: ‘TDecumentselect ions sStiacki£y(). const 
Create a new anchor using the document selection specified in this as the specification for the anchor. 


TDocumentSelection* TDocumentSelection::Duplicate() const 
This routine provides a polymorphic clone capability to all selections. You must override this method 
until the Utility Classes provide similar functionality. The typical way to override this method is: 


return new TMyType(*this); 


Anchors & Links 


Anchors are typically “sticky” document selections. By sticky, we mean that the anchor is resistent to 
editing changes ina document. When creating their own kinds of anchors, applications must use great 
care to insure that the information encapsulated in their subclass is enough to find the document selection 
independent of any change to the document. For example, a document selection in a text document is 
typically a range of characters. An anchor representing that selection needs more information because 
that range will typically be ad an editting change. One possible repre 
would be an index into a application and saved with the: € 

the document. 


cae 


3tiOn 
He data in 


Links are connections b ICCTEEWE BRCHEE rations on links include 


CCH EWONAL IDET them, removing them, 
“following” them, pu data from one sticky selection to the other, 


ata. 


TBaseAnchor 


The TBaseAnchor cl 
derive. It encapsu 
identifiers are assign 


class TBaseAnchor : public | 


public: 
virtual unsigned long 
virtual void Se 
virtual const TEntityID& Ge 
virtual bd 
protected: 
TBaseAn 
}; 
TSurrogateAnchor 


The TSurrogateAnchor provides the class which represents a surrogate for an actual anchor in the 
system. TSurrogateAnchorsare relatively cheap to pass around and can be turned into a real anchor 


using a method of TModel (assuming, of course, that this is a surrogate for an anchor in your model. If 
not, using the anchor as a surrogate is the only way to use it). 


class TSurrogateAnchor : public TBaseAnchor { 
public: 
TSurrogateAnchor (const TBaseAnchoré&) ; 
TSurrogateAnchor(); 
virtual ~TSurrogateAnchor(); 
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TAnchor 


The TAnchor class is an abstract baseclass which defines the protocol all anchors follow. Anchors contain 
a TDocumentSelection and are MSelectable objects. All methods of MSelectable are delegated to the 
embedded TDocumentSelection. They can be overridden if this is not the proper behavior. Subclasses of 
TAnchor should override methods to implement specific behavior for their kind of TAnchor. Subclasses 
should contain whatever information is necessary to find the appropriate “selection” independent of any 
editing changes to the document (or insure that the embedded document selection is resistent to editing 
changes). 


class TAnchor : public TBaseAnchor, public MSelectable { ° 


public: 
virtual void Touch (); 
virtual const TTimeé GetModifyDate() const; 
virtual void SetModifyDate(const TTime& modifydate) ; 


virtual void 


Selection(const TDocumen: 
virtual const ws 


GetDocumentSelecti 


virtual 
virtual voi 
virtual TA 
virtual vo 
protected: 
TAnchor ( 


eanst THyperLinks& 

Receive(const TDequeés& 
rx Duplicate() const; 
ClearData(); 


}; 


const TTime& TAnchor: :GetModifyDat 
Return the modification date for the data spe 
automatic update mechanism to send notifica 
currently impleny 


Ormation is u! 
ata (NOTE: F 


void TAncho 
Set the modificati 
specitied by the anche 


modifydate. The modificatio vhen the data 


void TAnchor: : Touch () 
Shorthand for SetModifyData(TTime: :Now()); 


void TAnchor: :SetDocumentSelection(const TDocumentSelectioné) 
Set the embedded document selection to the passed in selection. The old embedded selection is deleted 
and the passed in selection is copied. 


const TDocumentSelectioné& TAnchor::GetDocumentSelection() const 
Return a reference to the embedded selection. 


void TAnchor::Follow(const THyperLink& theLink) 

Override this method to implement your follow behavior. The TFollowedCommand will call this method 
on the followed anchor before posting the follow stimulus. The default method brings all of the 
document's presentations to the front using the following code: 
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TIterator* anIterator = GetModel()->GetPresentationIterator(); 


TPresentation* aPresentation = (TPresentation*) anIterator->First(); 

while (aPresentation != NIL) 

; : | 
aPresentation->Get View () ->GetLayer() ->GetSystemLayer()->BringToFront (); 
aPresentation = (TPresentation*) anIterator->Next (); 


} 


delete anIterator; 


void TAnchor: :Receive(const TDeque& theData) 
This method is called when data is pushed or pulled into the anchor. The default implementation is: 
ClearData(); . 
TDocumentSelection* retval = AcceptData(theData); 
if (retval != NIL) 
delete retval; 


TAnchor* TAnchor::D 
This routine provides a p 
until the Utility Classes p 

return new TMy 


to all selections. You mu this method 


. The typical way to ove 


void TAnchor::Cle 
This method is called. 
push/ pull semantics. € 
implementation is: 


fDocument Seles 


ata () 
Receive when data is pushed or pulled int 
tare-equivalent to select, copy, follow. 


r. This is part of the 
paste). The default 


THyperLink 


The THyperLink class provides the repress 
subclassing TAnchor. There are no subclasst 
anchor are just names for the two anchors in 
part of the current document and can be turn 
“there” anchor#may be-part of the current d 


Class THype 
public: : 
THyperLink (con 


£rogateAnchoré here, 


const TSurrogateAnchoré& there, long uid 0); 
virtual const TSurrogateAnchoré& GetHere() const; 
virtual const TSurrogateAnchor& GetThere() const; 
virtual unsigned long GetUniqueID() const; 
virtual void SetUniqueID(unsigned long); 


+3 


Models, Documents, and Model Servers 


Three classes in CHER represent a superset of the functionality available in MacApp. The main class that 
application writers should concern themselves with is TModel. Subclasses of TModel will contain all of 
the “document” data. TModel objects provide change notification to interested presentations. The 
TModel baseclass provides very little functionality; however, it does provide protocol which all models 
are expected to implement. 
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Unlike TModel, TModelServer provides a great deal of behavior for talking to other models and model 


servers. TModelServer subclasses act asa global controller to the model’s data. It coordinates the 


application of command objects to all collaborators accessing the document. Only one method ot 
TModelServer typically needs to be overridden. 


TDocument subclasses act as a kind of local controller to the model’s data. Again, very little overridding 
is necessary in TDocument. 


TModel 


The TModel class is the object to which command objects are applied. It contains all of the data ina 
document, all of the links and all of the anchors. The TMode1 class provides a change notification service 
so interested presentations are notified when changes occur to the model. The model defines protocol for 
saving and restoring all of the data associated with the model. 


class TModel 


pub 


public: 

virtual voi 

const TToken* whe 
virtual vo CancelRegistration ( 

TPresentation 

const TToken NIL 
virtual ed(TStimulus# : 
virtual 
virtual 
virtual void 
virtual void Hid.3 
virtual TIterator* 
virtual const TSet* 
virtua o chor(TSure 
virtua: riterator ( 
virtua PendingClipboardDat & 
virtual MCobLeécet: GetPendingClipboardData ( 

const TTypeDescription* theType = NIL); 
virtual const TDocumentSelection* GetDocumentSelection() const; 
virtual void SetDocumentSelection ( 

const TDocumentSelection*); 
virtual void EstablishDocumentSelection ( 

const TDocumentSelection* newSelection, 
const TDocumentSelection* oldSelection = NIL); 

virtual void Acquire (); 
virtual void AcquireShared(); 
virtual void Release(); 
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void TModel: :RegisterClient (TPresentation* whoToNotify, 
const TToken* whatChanged) 
Call this method to register a presentation to receive change notification. If the token is NIL, all changes 


will be notified. If the token is non-NIL then only notification stimuli which match the whatChanged | 
token will be sent. 


void TModel::CancelRegistration(TPresentation& whoToNotify, 
const TToken* whatChanged) 

Cancel change notification for a specific presentation. The what Changed variable should match the 

whatChanged ina previous RegisterClient. 


void TModel::Changed(TStimulus* changeStimulus) 


Call this method to force change notification to occur. The change stimulus is propagated to all interested 
presentations via the normal responder/event mechanism. The stimulus should be put on the heap. It 


will be managed by the system. 


void TModel::Set 
Set the model server t 
vour address space. 


ver* theModel) 


. This only works if there server object in 


>GetModelServer() const 
yer Object in your address space or NIL if 


TModelServer* TH@del: 
Return the model s 


void TModel (TPresentation* 


tions on this mode 


Remove a presentatie 


TIterator* TModel: :GetPresen 
Return an iterator which the application 
presentations. 


const TSet* TModel::RetrieveLin : 
Retrieve a set< ing all of the links th ital del. 
NOTE: This wall soon be fixed. 


TAnchor* =¢TSurrogateAnchoré ar 

Givena TSurrogat ; return the real TAnchor object that th ‘te anchor is a surrogate 
for. Of course, this only works for anchors in your own document. SurrogateAnchors in other 
documents will not be found and the call will return NIL. 


TIlterator* TModel::GetAnchorIterator() const 
Return an iterator which the application must manage. This iterator will iterate through all of the 
anchors. 


void TModel: :SetPendingClipboardData (MCollectible*) 

The current (very temporary) implementation of the clipboard uses two methods which you must 
override to store away the current contents of the clipboard during a cut or copy operation. The system 
will remember which document (model) contains the current clipboard data. Your 

Set PendingClipboardData routine should discard the old clipboard data and store the passed in 


data. It will always be in your native type. The corresponding Getter (below) will return the data in 
multiple types. 
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MCollectible* TModel: :GetPendingClipboardData ( 

const TTypeDescription*. theType) 
Return the pending clipboard data (previously stashed away with Set PendingClipboardData) using 
theType as the return type. 


const TDocumentSelection* TModel::GetDocumentSelection() const 
Return what the model thinks the current document selection is. 


void TModel::SetDocumentSelection(const TDocumentSelection*) 
Set the document selection to a copy of the passed in selection. 


void TModel::EstablishDocumentSelection (const TDocumentSelection* newOne, 
“const TDocumentSelection* oldSelection) 
EstablishDocument Selection is called by many command objects to set the selection after they are 
complete to establish the new selection (e.g. aftera TReplaceSelectionCommand). The default code 
forEstablishDocumentSelection.is: 
if (oldSelection # 
oldSelection 


TDocumentSelect 
if (theSelectio, 
newSelection 


= NIL) 
theSelection->Duplicate(); 


TDualDocument$ 
new TDu nStimulus (kEs 


Changed (s); 


delete newSelection; 


void TModel: :Acquire () 
Acquire the model semaphore read/write. 


es this when 
being executed. Long running commands ca 


ed; release 
nice citizen: 


void TModel 
Acquire the m 
semaphore shar 
the model semap 


ers and presentati} 


1 acquire t 
72 model. Of course, trac 


presenta Hould release 


void TModel: :Release () 
Release the model semaphore. 


TModelServer 


TModelServer is an abstract superclass which implements much of the global behavior associated with 
applying commands to a document. I[t controls the collaboration (if there is one), it talks to the desktop 
manager and other system services to accomplish linking and data exchange. The model server object 
logs command objects to disk to add to the reliability of your program. There are many methods of the 
model server; however, only one is necessary to get started with CHER. 


class TModelServer : public MServer, public MEventSource { 


protected: 
TModelServer(const char* theModel) ; 
virtual TModel* DoMakeModel (TModelServer* theModel) = 0; 
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TModel* TModelServer: :DoMakeModel (TModelServer* theModel) 
Override this method to make the kind of model associated with your document. The usual override tor 
this method ts: 


return new TMyModel(); 


TDocument 


TDocument is an abstract superclass which acts as a kind of local controller to the model’s data. The 
TDocument object applys commands to the model and assists presentations in finding the appropriate 
model for querying. Command objects are applied in a separate thread. This allows user interface stuff 
to be going on at the same time command objects are applied. Long running commands should explicitly 
release the model semaphore when appropriate (see TCommands). 
class ‘TDocument blic TModelClient { 
public: 
virtual 
virtual 
virtual 


tpBeforeQuit(); 


virtual vo SetCachedModel (TM 


virtual GetCachedModel (): 
virtual SetQueryModel (T 
virtual 
virtual 

virtual 


protected: 
TDocument (const TTexté& na 
Virtual -vord 
virtual TModel* 
virtual MBaseTask* 


FALSE) 


OF 
TEntityl 


St TText& 
leané& stat 
wa keQueryModel t 
@tModelServer (TMo 
GetUseLocalCache() c 


a 


TDocument::TDocument (const TText& name, Boolean useLocalCache) 
Create a new document. Methods that are overridden in your subclass of TDocument control the kind of 
model server created and the kind of model created. If you are collaborating and you are not the 


“collaboration server,” (i.e. you don’t have a model server on your machine) then set useLocalCache to 
true to force a local copy of the model on your machine. The name that is passed in is the “entity” name 
of the document. 


void TDocument::StartTheDocument () 
Most of the real work in document creation doesn’t happen until this method is called. This is to get 
around the problem of calling virtual functions in constructors (thanks, Barney). The first thing that 


happens at startup is finding the model server. This is accomplished by calling FindModelServer. If 
there is to be a local cache, DoMakeCachedModel is called. Then DoMakeQueryModel1 is called. Finally, 
DoMakePresentations Is called. 
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TModel* TDocument: :DoMakeCachedModel (const TEntityID& eid) 

The cached model is the model to apply command objects to in your address space. If the model server 
(and its associated model) are not in your address space (i.e. you are collaborating), you will probably 
want to have a cached model (If you don’t have a cached model and you are collaborating, you must 
have a query model. See below). Typically, this is overridden to: 


return new TMyModel (eid) ; 


void TDocument: :DoMakeQueryModel (const TEntityID&é&) 

The query model is the model your presentations will use when querying the model. Typically, this will 
be the model server’s model if you are not collaborating or the cached model if you are collaborating. If 
these defaults are okay, then do not override this method. Alternatively, you could define a “query” 
model whichsupported the protocol of your normal model but communicated with the model server to 
fulfill any requests. 


void TDocument: :DoMakePresentations () 
Override this method to create the presentations associated with the document. These presentations 
should register with the m ificati 


MBaseTask* TDocumes onst TTexté& theModel, 


Find or start the model 
you are not worried abot 


me but will soon. If 


Boolean TDocume 


This method defaults This will be 


Return the TModelServer ¢ same add 


re address $: 


Presentation 


TPresentat 
registered wit 


calling the Model 


model, af ations 
fication 


he change will receive ch 
‘Presentation. 


class TPresentation : public MCollectible { 


public: 
virtual void SetView(TView* theView) ; 
virtual TView* GetView() const; 
virtual void SetModel (TModel* theDocument) ; 
virtual TModel* GetModel() const; 
virtual void Mode 1lChanged ( 


TModel* theModel, 
TStimulus* theChange) ; 
virtual MResponder* GetResponder ( 
TModel* theModel = NIL, 
TStimulus* theChange = NIL); 
protected: 
TPresentation(TView* theView = NIL, TModel* theModel = NIL); 
Ve 
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void TPresentation: :ModelChanged(TModel* theModel, TStimulus* theChange) 
When the model changes, this method is called. The default implementation for this method is: 
(GetResponder ()) ->Respond(theChange, TRUE) ; 


MResponder* TPresentation: :GetResponder (TModel* theModel, 


TStimulus* theChange) 
This is called by the default ModelChanged implementation to return what responder should be sent this 
notification. The default implementation of this method is: 


return GetView(); 


The CherApp 


This class is a temporary class until CHER is integrated with the normal Pink Release. 


class TCherApp 
public: 


TCherApp ( 
Char =e 
MRespon eo Ri 1é NIL, 
Applic kRunningStat 


virtual SetDocument (TDocument*) 
virtual : tek: 
}; 


TCherApp: :T 2 Responder * 


Create a new TeherApp. This 
integrated with the user interface stulf: 


Command Objects & Stimuli 


1 change the 
redone.” Cont 


late a user action ar 
yne,” “undone,” 


Command obje 
Command obj 


document selec 7 
protocol that all ce id to. Gubelsceas of TComma: 
HandleRedo, and Hand: 


CHER will provide the basic command objects for: cut; copy; paste; selection; starting links; completing 
links; following links; pushing data on a link; pulling data on a link; adding anchors to a document, and 
adding links to a document. It should not be necessary to override any of these command objects. 
Implementing the selection protocol will be enough to get all of these commands to work. The result of a 
command usually involves posting a stimulus to all of the interested presentations. The kind of stimulus 
posted by these command objects will be discussed with each command. 


Many commands built into CHER have both a local effect and a global effect. For example, the cut 
command has the local effect of removing the current selection from the document. The cut command 
has the global effect of adding the current selection to the clipboard. Only the local effect of a command 
is undoable in the application that the command was done. The global effect is undoable in the global 
context (i.e. by going to the clipboard in this case). Almost all commands that developers will write 
themselves will only have a local effect. To implement this behavior, the HandleDo method of a 
command will do the global effect (with the help of the model server) and as the last statement of the 
HandleDo method doa return TOtherCommand->HandleDo();. 
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All command objects save the selection before the command is executed and restore the selection after an 
Undo by calling the model’s EstablishSelection method. 


TCommand 


class TCommand : public MCollectible { 


pubiac: . 
enum FlattenIntensity { kEverything, kDoOnly } ; 
public: 
virtual TCommand* Do (TModel* theModel) ; 
virtual TCommand* Undo (TModel* theModel) ; 
virtual TCommand* Redo (TModel* theModel); 
virtual void SetDocument (TDocument*) ; 
virtual ) const; 
virtual } Model*); 
virtual 3 const; 


SetDocumentSelection(¢ SumentSelection*); 


virtual voi 
; TDocumentSelection* GetDocume: On() const; 


virtual c 


virtual etFlatteniInten 

virtual StFlattenInte 

virtual =BS: syHandleDé 
protected: 


TCommand (const TDocumentSe 


public: 
virtual TCommand* Handl y7 
virtualL.<it@ommand* Handli ron @ i 
virtua) sdo(); 
virtua ndIsUndoable() 7: 


TCommand: :TCommand(const TDocument Selections) 
Create a new TCommand object. The command object will eventually be applied to the passed in 
selection (if supplied) or the model’s current selection (if it applies to a selection and none was supplied). 


TCommand* TCommand: :Do(TModel* theModel) 
This method contains the machinery for “doing” the command. Eventually it calls the HandleDo method 
which you should override. 


TCommand* TCommand: : Undo (TModel* theModel) 
This method contains the machinery for “undoing” the command. Eventually it calls the HandleUndo 
method which you should override. 


TCommand* TCommand: :Redo(TModel* theModel) 
This method contains the machinery for “redoing” the command. Eventually it calls the HandleRedo 


method which you should override. 
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void TCommand: :SetDocumentSelection(const .TDocumentSelection*) 
Set the selection that this command object will apply to. 


const TDocumentSelection* TCommand: :GetDocumentSelection() const 
Return the selection that this command object will apply to. 


void TCommand: :SetFlattenIntensity(FlattenIntensity) ; 
CHER will log command objects to the disk to add reliability to your application in case of extraordinary 
failures. Logging these command objects only involves logging the “do” part of the command. The 


flatten intensity is set to kDoOn1y when logging command objects and kEverything at other times. 
Your operator>>= routine should check the flatten intensity using Get FlattenIntensizy when 
flattening. Your operator<<= routine should be able to expand an object flattened with any intensity. 


FlattenIntensity TCommand: :GetFlattenIntensity() const 
Return the current flatten intensity. 


TCommand* TCommand: : 
Override this method to 18 


command will probably 
The exception is when y¢ 
returns new TRepl 
semaphore in this meth 


‘result of your 
FOM HandleDo. 
-TPastetommand 


1 release the model 
ye command. 


and does when “doing.” The 


o: mriand using another co 


sSelection command). Long running cor 
. They should reaquire the semaphore bef¢ 


TCommand* TComma 
Override this metho timate result of 

your command wil BANS an release 
the model semapho t mand. 


Override this method to implement what ‘ 
your command will probably post a stimultés 
the model semaphore in this method. They s 


and become 
TReplaceSelecti S.) 


Boolean TComman ad 1 : 
[f your command object doesn’t change state during HandleDo (other than saving undo information), 
then an optimization can be made during collaboration. If the command objects changes (or one of the 


embedded objects changes) then this should return TRUE. 


TCommandGroup 


A command group is used to group a set of command objects that should be viewed as an indivisible unit 
for the purpose of do, undo, and redo. An example of when a command group 1s created is after the user 


issues a complete link command. Eventually, this turns into a group of commands: TNewAnchor & 
TNewLink. _ 


class TCommandGroup : public TCommand { 


public: 
TCommandGroup (); 
virtual void AddFirst (TCommand*) ; 
virtual void AddLast (TCommand*) ; 
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virtual TCommand* Remove (const TCommands&); 
hy 


void TCommandGroup: :AddFirst (TCommand*) 
Add the passed in command as the first command in the group. 


void TCommandGroup: :AddLast (TCommand*) 
Add the passed in command as the last command in the group. 


TCommand* TCommandGroup: :Remove (const TCommandé) 
Remove the command that IsEqual to the passed in command. 


TSelectCommand 


The TSelectCommand should be issued when See ae dhe selections in the document if you want 
selections to be undoable. ; WTS 
HandleRedo, or Handlet 
EstablishDocuments 


class TSelectComm 
public: 
TSelectComm 


const TDocumentSelection& th 


he 


TCutCommand 


The TCutComman 
global effect of adding something 


TCutCommand into a TReplaceSe 


the current $ 


class TCutCommand : public TComm 
PUbLis? 
TCutCommand (const TDocumentSe 


The TCopyCommand has no‘local'effect. It has the global effect of putting something on the clipboard. 


class TCopyCommand : public TCommand { 
public: 
TCopyCommand(const TDocumentSelectioné&) ; 
bi 


TPasteCommand 


The TPasteCommand replaces the current selection with the “top” of the clipboard. This is accomplished 
by turning. the paste command into a TReplaceSelect ion command. 


class TPasteCommand : public TCommand { 
public? 
TPasteCommand(const TDocumentSelections&) ; 
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Ao ae 


ie 


TReplaceSelectionCommand 


The TReplaceSelect ionCommand replaces the data specified by a selection or anchor with data 
encapsulated in the command object. The command object contains a TDeque of TTypeDescription, 
MCollectible* pairs which should be used when replacing the selection’s data. A 


TDocumentSelectionStimulus with the token “DocumentSelectionContentsChanged” is issued 
as a result of this command. After this stimulus is posted, the model method, 


EstablishDocumentSelection, is called if the act of replacing the selection caused a new selection to 


be created. You will typically never createa TReplaceSelect ionCommand yourself. CHER creates this 
command object as a result of cut, paste, push, pull, etc. 


class TReplaceSelectionCommand public TCommand { 


public: 
TReplaceSelect ‘umentSelection&); 
TReplaceSelect Anchoré theAncho 
virtual TDeq ~~ GetData (); 


virtual vo 


AddData ( 
const TTypeDescriptig 
MCollectible* theD 


virtual v (MCollectible* 


TNewAnchorComman 


The TNewAnchorCommand is issued wher 
becomes a TNewAnchorCommand after the g 
TNewAnchorCommand is done or redone, a T 
“AddAnchor” is posted. If the TNewAnchorC 
with the token “ "4 


TStartLhLi 


class TNewAn 

public: . 
TNewAnchorCommandéTAncnor* anAnchor) ; 

virtual TAnchor* GetAnchor() const; 


+e 


TNewLinkCommand 


The TNewLinkCommand is issued whenever a new link is created. A TCompleteLinkCommand becomes 
aTCommandGroup with TNewLinkCommands embedded in it after the global effect of TCompleteLink 
is done. After the TNewLinkCommand is done or redone, a THyperLinkStimulus with the token 
“AddLink” is posted. If the TNewLinkCommand is undone, a THyperLinkStimulus with the token 
“RemoveLink” is posted to all interested presentations. 


class TNewLinkCommand : public TCommand { 
public: 
, TNewLinkCommand(const THyperLink& abLink); 
virtual const THyperLink& GetLink() const; 
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pala iar 


be 


TStartLinkCommand 


The TStart LinkCommand has the global effect of putting a new anchor on the “link board” and the local ° 
effect of adding a new anchor to the document. The local effect is accomplished by CHER issuing a 
TNewAnchorCommand. 


class TStartLinkCommand : public TCommand { 


public: 
TStartLinkCommand (const TDocumentSelections) ; 
virtual TAnchor*. GetAnchor() const; 


be 


TCompleteLinkCommand. 


The TCompleteLinkC 
new link command to a 
local effect of adding ark 
appropriate command 


k. It has the (possibly) nan= 
tment which issued the 
Trent document. Thi 


jects (TNewAnchor and TNewLink). 


fect of posting a 
command). It has the 
plished using the 


class TComplete public TCommand { 


public: 
TComplete * theAnchor, 
TComplete SgheAnchor) ; 
virtual : 
}; 
TPushDataCommand 


The TPushDataCommand has the (possibly) ni 
command to the destination anchor. All type: 


class TPus 
public: 
TPushData 
const nchor& sourceAnchor, 
const TSurrogateAnchor& destinationAnchor) ; 
virtual const TSurrogateAnchoré GetSourceAnchor() const; 
virtual const TSurrogateAnchoré GetDestinationAnchor() const; 


}3 


TTickleCommand 


The TTickleCommand command could be called the pull command. It isa command object which tells 
the other anchor to push data to me. This is accomplished by forcing the other side of the link to issue a 
TPushDataCommand. 


class TTickleCommand : public TCommand { 
public: 
TTickleCommand ( 
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ee 


const TSurrogateAnchoré& sourceAnchor, 
const TSurrogateAnchoré reply); 
virtual const TSurrogateAnchoré GetSourceAnchor() const; 
virtual const TSurrogateAnchoré GetReplyAnchor() const; 
be 


TFollowCommand 


The TFollowCommand will “follow” a link. This involves posting a TFol lowedCommand to the 
document containing the other side of the link. - 


class TFollowCommand : public TCommand { 
public: 
TFollowCommand(const THyperLink& theLink); 
virtual const THyperLinks«..GetLink(}) const; 


PG 


TFollowedCommand 


The TFollowedComma 
“there” side of the T 
Follow method of the 
follow behavior (typi 
with the “Follow” t 


is posted to the document containing the.¢ 
rLink embedded | in the TFollowedCom 

x will be called. Overrid 
and its selection int@ 


zanchor ina link. The 
zestination anchor. The 
to implement the proper 
‘LinkStimulus 


Class TFollowédGonm 
public: 

ero LowedConmand(eonst: TH 

virtual const THyperLinké& 

3 


Stimuli 


The stimulus th: 


the kind of objects: 
actual stimulus 


Ommand is discussed ve 


ated inthe 


Ferelepeat ihe tasceeeag ots setete 


class TSurrogateAn 
public: 
TSurrogateAnchorStimulus ( 
const TToken&é theStimulus, 
const TSurrogateAnchoré& theAnchor, 
TModel* theModel); 


public TStimulus { 


virtual const TSurrogateAnchoré GetSurrogateAnchor() const; 
virtual TModel* GetModel() const; 
}; 


class THyperLinkStimulus : public TStimulus { 
public: 
THyperLinkStimulus ( 
const TTokené&é theStimulus, 
const THyperLinké, 
TModel* theModel); 
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ene nan on 


virtual const THyperLinks GetHyperLink() const; 


virtual TModel* GetModel() const; 
3 
class TDocumentSelectionStimulus : public TStimulus { 
Public: 


TDocumentSelectionStimulus ( 
const TToken& theStimulus, 
const TDocumentSelection*) ; 


virtual const TDocumentSelection* GetDocumentSelection() const; 


Pe 


class TDualDocumentSelectionStimulus : public TStimulus { 
public: 
TDualDocumentSe 
const TT 
const TD: 
const T 


tion () 
slection() 


virtual con 
virtual con 


* TDocumentSelection* GetFirstDoces 
TDocumentSelection* GetSecondh% 
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const; 
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Introduction 


The Event Server is primarily concerned with receiving events from the various devices attached to the 
system and distributing them using some well known protocol to applications in the system. There are a 
number of design goals for the Event Server presented here in no particular order. First, it must be 
reliable and it must not block because of a runaway application. It should not be possible for an ill-be- 
haved application to take down the user’s means of communicating with the system. Second, it should 
allow for events to be generated by previously unknown devices in a reasonable way. And, finally, it 
should be very easy for the developer of device drivers and applications to use. All of the external 
interface should hide any implementation details such as the use of Opus/2 messages, shared memory, 
and so on. $ 


Overview 


There are a small number of.co j . Event Server need to know. In theo: 


application developers wi sented in this document. The Pin 
Message System is respon 


fo the application. So, the clis 
in this document are writ plementor of the Pink Evé 
_ and adapter authors. 


Ae information 
Message System, 


#s and applications in the 
: Server which is used for 
n the Event Server and the 


system can find it. Th 
all communication wt 
Layer Server to dete 
of a positional event 
frontmost layer. 


vent Server instantiates a surrogate object: 
er. Communication is nece 


Devices instantiate a Surrégate: : 
communication with the Event Serve fe t BD Sa 
predefined type of event called TOSEvent | SS 
TOSExtendedEvent has been provided. : 2 


© 


wWoacacccag 


“Keyboard 


find it. ~ Name Server 
Event Server queries the Name 
Server to find the Layer Server. It 
will need to communicate with 
this dude later. 

Laser she 
When devices start up, they 
register themselves with the : 
Event Server. Event Server 


Layer Server 


©O © 


Figure 1 - What happens at startup time. 
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Once the Event Server has started up, it blocks on events to be posted by the devices attached to the 
system and then distributes these events to the proper applications. The Event Server does not believe 
that applications will be well behaved and thus takes necessary and adequate precautions against an evil 
application from taking over the machine. 


When the user presses the mouse button (refer to Figure 2), an event is generated by the mouse driver 
and this event is sent to the Event Server using the DistributeEvent method. The Event Server re- 
ceives the event, realizes that this event isa positional event and is to be distributed based on the 

application “under” the device. The Event Server queries the Layer Server to determine which task is 


The user presses the mouse c ory 

button down and the mouse Mouse 
driver generates an event and 

passes it to the event server. 


O) The Event: 


the mouse. 


responsible for receit Ss ; application. The Pink 
Event and Message Syste nder object will 
receive the event. 


In the case of a keyboard event (refer to Figure 3), the event is quickly passed onto the application 
because the surrogate LayerServer has cached the information concerning which application is the target 


of the keyboard. 
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The user presses a key on the Kovboard 
keyboard and the keyboard ae 
driver passes this information to 

the event server. Name Server 


The Event Server has cached 
who the target of the Laser ... 
keyboard is (that is, which 
task will receive the event). 
Tne keyboard event is then 
sent to the application. 


Layer Server 


Event Server 


Classes 


The classes presented here are used internall: 
Currently there is an architecture which sup 
changing toa variable size event for all event 

et, most of you reading 


unless you are: 


TEventServer 


The TEventServer object is an abstract baseclass which encapsulates the protocol for talking to the real 
Event Server. The TEvent Server object lives in your address space and talks to the real Event Server 
which lives in its own address space. This saves the application framework writer from having to know 
about the nasty details about Opus/2 IPC messages. It also insulates us so that future changes can easily 
be made to this protocol when porting the code to other architectures that allow messages of different 
sizes or different synchronization methods. 


class TEventServer : public MServer, public MClient { 
public: 

virtual ~TEventServer(); 

virtual void Main(TMemory& startupInfo) ; 


protected: 
TEventServer(char* myprogramname, 
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const TTaskSchedule& theExecutionCategory = kServerTask, 
size_t aStackSize = kDefaultStackSize) ; 
virtual void NewEvent (); 
virtual void ~ HandleNextEvent (TOSEvent*, TOSExtendedEvent*) = 0; 
virtual TOSEvent* AllocateTOSEvent (); 
Pe 


TEventServer::TEventServer(char*, const TTaskSchedule&, size t aStackSize) 
Create the TEvent Server object. Since this is an abstract superclass, the constructor can only be called 
by a subclass. You must override the HandleNextEvent () method to get this object to do anything. 
Remember, because a TEvent Server is a MTask, your particular subclass must be started after it is 
created (by calling the virtual function Start ()). 


TEventServer: :~TEventServer () 
Destroy the TEvent Server object. 


void TEventServer 
Override this method if 


when the TEvent Serv. 
the inherited Main (). 


DINLO) 
‘t get done in the construg 


ust get done 
this method is call 


void TEventServ 
This method receive 
which you need to o 


NewEvent () 
ext-event from the EventServer and ca 


leNextEvent routine 


Override this meth: 
associated with the TOSExten 


TOSEvent * should be managed ina W 
See below. 


TOSEvent* TEvent Server: *AllocateT@ 


one on the h eed to 
OSEvent 


MeEventSourc 


All devices that will be generating events should be subclasses of MEvent Source. Devices use these 
methods to register themselves with the Event Server and to post events. 


class MEventSource : public MClient { 
SuUbLic: 
virtual ~MEventSource(); 


protected: 
MEventSource(); 
virtual void RegisterDevice(DeviceClass, DeviceName, 
Boolean async = FALSE) ; 
virtual void DistributeEvent (TOSEventé, TOSExtendedEvent* e = Ni Ly 
Boolean async = FALSE); 
virtual void PostEvent (TOSEventé, TOSExtendedEvent* e = NIL, 
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Boolean async = FALSE); 
virtual void PostEventToTask(const TSurrogateTask&, TOSEvent&, 
. TOSExtendedEvent* e = NIL, Boolean async 
virtual void PostEventToLayer(const TSurrogateLayeré&, TOSEventé&, 
TOSExtendedEvent* e = NIL, Boolean async = FALSE); 


FALSE) ; 


Pe 


MEventSource: :MEventSource () 
Create a new MEvent Source surrogate object. This object is used by the device driver for all 
communication with the Event Server. 


MEventSource: :MEvent Source () 
Destroy the MEvent Source surrogate object. 


void MEventSource: :DistributeEvent (TOSEventé&, TOSExtendedEvent*, 


y have an 
Sent unless the 


=) 
ionally should call this method 
real Event Server has re¢ 


Devices which want to h 
event to distribute. Note 
async flag is set. 


PostEvent (TOSEvent&, TOSExtended 
Boolean async) 

ave an event posted nonpositionally shou 
until the real Event Serv¢ 


void MEventSourc 


Devices which want t 
event to post. Note tk 
flag is set. 


rethod when they have an 
i the event unless the async 


void MEventSo fonst TSur 


Devices which want to have a 
to post. Note that this call blocks until't 


void MEventSource: :PostEventToLays 
Devices which want to have an event posted t 3 ich: n use 


unless the asyn¢ 


({DeviceClass, Deve 
This method shou vices that wish to register thems 
DeviceClass and DeviceName | token ids. Use the token manager : 
device class would be the token id for “Mouse.” An example device name would be the token id for 
“Primary.” 


void MEventS 


The TOSEvent Components 


There are a number of classes (actually structs) which are used to represent the TOSEvent. Only the 
header is repeated here as the classes only provide methods for getting, setting, flattening and expanding. 


// Typedefs 
typedef TokenID DeviceClass; 
typedef TokenID DeviceName; 


// Temporary until we have the real time stuff 
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typedef HardwareTime EventTime; 
typedef short VirtualKkey; 
typedef TokenID WellKnownEvent; 


class TModifier { 
private: 


unsigned char fBits; 


public: 


public: 
TWellKnownSi: 
void Se @lean on= T; 
Boolean Ge: : 
void Se: sedn 
Boolean GetCausedNonP t 
void SetEventDistributed 
Boolean GetEventDistributed 
void SetNeverSwitchLayers (B 
Boolean GetNeverSwitchLayers () 


be 


class TOSEV, 
Public: 


TModifier(); 
void SetOptionKey (Boolean on= TRUE); 
void SetCapsLockKey (Boolean on= TRUE); 

void SetShiftKey (Boolean on= TRUE); 

void SetCommandKey (Boolean on= TRUE) ; 

void SetControlkKey(Boolean on= TRUE) ; 

Boolean GetOpt ionKkey.(.)....8 
Boolean GetCapsL 
Boolean GetShifti 
Boolean GetCommay 
Boolean GetCont. 


TOSEvent () 
TOSEvent (Well KnownEy ent) ; SSE 
TOSEvent (DeviceClass realDevice, DeviceName deviceName, TGPoint where, 
TModifier modifiers, WellKnownEvent event) ; 
TOSEvent (DeviceClass dclass, DeviceName dname, WellKnownEvent event); 
TOSEvent (DeviceClass realDevice, DeviceName deviceName, 
TModifier modifiers, VirtualKey key,WellKnownEvent event); 
TOSEvent (WellKnownEvent event, const TSurrogateLayer& newLayer, 
const TSurrogateLayer& oldLayer) ; 
TOSEvent (WellKnownEvent event, const TSurrogateLayer& newLayer) ; 
TOSEvent (DeviceClass dclass, DeviceName dname, WellKnownEvent event, 
LayerID aLayer); 
TOSEvent (WeliKnownEvent event, LayerID aLayer); 


DeviceClass GetActualDevice() const; 
DeviceClass GetActingLike() const; 
DeviceName GetDeviceName() const; 
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EventTime GetWhen() const; 


void GetWhen(TTime& aTime) const; 

TGPoint : GetWhere() const; 

TModifier GetModifiers() const; 

VirtualKkKey GetKey() const; 

WellKnownEvent GetEventType() const; 

TWellKnownSideEffects GetSideEffects() const;; 

void GetNewSurrogateLayer (TSurrogateLayer&) const; 
yoid GetOldSurrogateLayer (TSurrogateLayer&) const; 
LayerID | GetLayerID() const; = 
void SetLayerID (LayerID); 

VOU: -: ' SetActualDevice (DeviceClass dev); 

void SetActingLike (DeviceClass dev); 

void SetDeviceName (DeviceName dname) ; 

void SetWhen (EventTime when) ; 


void '& where); 

void Modifier modifiers) ; 

void Key key); 

void WellKnownEvent ey 

void “ effects); 
TStream& operator>>=(TStreamé) 

TStream& merator<<=(TStream&) ; 


The TOSExtendédE 


TOSExtendedEvent subclasses are us 
TOSEvent because they won’t fit in an Oput 
virtual functions, etc. Because of this flexibilit: 
device driver) must provide implementations 
extended events for transmission using the op icati sm. 
Soon after d11, T¢. ndedEvents willb You will b 
TOSEvent (or lass for event events. 


class TOSExter 
public: 
TOSExtendedEvent (); 
virtual ~TOSExtendedEvent (); 


virtual TStreamé operator>>=(TStream& towhere) const; 
virtual TStreamé& operator<<=(TStream& towhere); 
bi 


ine) 
to 
a 
“N] 
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Introduction 


The Pink scripting system is designed to give end-users the ability to automate 
their complex or repetitive tasks in a way that is easy se use, universally avail- 
able, and effective. 


Purpose 


End-User Task Encapsulation 


Repetitive actions are tedious. Complex actions are difficult to remember and 
are error-prone. Computers can be good at performing complex or repetitive 
tasks. However, they must be programmed. Unfortunately, this is not an option 
for:mastusers 


ple are usually 
ew applications for 
se people can never 
cases, adding features 
a better chance of 

g applications too com- 


are application developers 
ind are able to synthesiz 
jn to others. Unfortur 
Pp ry potential end-user 
making the application more flexible in ore 
peste a diverse set of needs has the dang 


for them- 


zation faciliti® 
HyperCard (Hy 
address the progr 
skills or desire to writ 
programmers and reg’ 
{Nicol 89}. 


their computer usage nee 
The primary purpose of the Pink scripting system is to provide these end-users a 
way to encapsulate their complex, repetitive, or procedural tasks. As such, it 


completes the set of programming systems necessary to satisfy the needs of the 
entire range of user types. 


Objectives 


The Pink Scripting System will be easy to use, universally available, and effective 
in its ability to automate end-user tasks. 


Easy to Use 


The Pink Scripting System will be easy and fun to use by end-users. It will be 
easy to enable, easy to disable, and easy to begin and control script execution. It 
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will be a tool that truly facilitates end-user tasks without getting in the way. 


The Pink Scripting System will not require much additional skill or knowledge. 
Additional skills may be required, however, for advanced features such as the 
ability to modify or parametrize a script. 


The Pink scripting system will employ a visual metaphor that is effective in dis- 
tinguishing the script, its subject or task, and its parameters, and that facilitates 
editing, execution, and debugging. 


Universally Available . 


The Pink Scripting System will be automatically available to users within and 
among all applications. It will require little additional effort for application de- 
velopers to enable the base functionality. Enabling some advanced features may 
require additional developer effort. 


execute the user’s 
asy to use. It is desir- 
ense of losing the end- 


will correctly capture, di 
ORE EUW as possible while ret 

ble that this system be Turing-complete, but n 
ser audience. 


Strategy 
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Features 


- The Pink scripting system will feature a visual scripting language, automatic task 
recognition and completion, explicit scripting by demonstration, an effective vi- 
sual metaphor, and flexible script modification. : 


Visual Scripting Language 


One of the most important aspects of the Pink scripting system is the program- 
ming language used to record scripts. This language will determine, in largé 
part, what programming constructs and operations are possible and how easy 
the system is to use. 


Language of the User Interface 


system will use the language of th 
ipts by performing the desi 
Sf objects, files, docume 
he emphasis will be pla 


‘ation them- 
cations, and com- 
ging rather than 

ire that they are “pro- 
; described as program- 
d as programming by 


g. 
amming’ “atall. This method of visual pr 
ping Py one [Halbert 84], as visual coaching 


¢ It does not require 
user interface em ‘amili nce 


¢ It does not require abstract linear thinking. This, according to Norman 
Cousins, “...is the most difficult work in the entire range of human effort...”. 
Scripting by demonstration gives users immediate visual feedback by em- 
ploying familiar operations. 


¢ Itis extensible. As new applications and new operations become available to 
users, these operations may be used in scripts. 


Automatic Task Recognition and Completion 


The Pink scripting system will attempt to recognize repetitive tasks within an ap- 
plication as the user is performing them. As the user continues to perform the 
task, the system will give visual feedback to demonstrate that it is anticipating 
the user’s actions. The user will then have the option of having the task 
completed automatically. This feature has been prototyped in HyperCard by 
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Allen Cypher [Cypher 89] and studied by the Apple Human Interface Group 


{Karimi 89]. 

Task Recognition 

The Pink scripting system will constantly monitor the actions that are currently 
being performed by the user. As it does this, it vgill attempt to recognize a repeti- 
tive task that could be completed automatically. 


This task recognition process must accommodate the following situations:! 


¢ Mistakes. Users will make mistakes while performing a complex sequence of 
operations. They will either undo these mistakes or will in some way correct 
the errant operation. The scripting system must be able to disregard these 
mistakes as it is looking for repetitive command sequences. 


Many applications offer users seve 


ime thing. For example, in this.v $rOCessor, one 
i’ sing the /talic 
@ Style... dialog 
lternatives cause the 
nt during task recogni- 


a sound t@ is 


Anticipation 
Once a repetitive task oni € é i i ted 


in confidence that i (; the 
jates from. i 


thod of indicating an anticipated us 2 

‘system. This could be a color or some other form of highlighting. Users will also 
be able to look at the automatically-generated script while the system is antici- 
pating user actions. 


Task Completion 


After the user is confident that the the system understands the repetitive task 
being performed, either through the anticipation feedback or by inspecting the 
proposed script, the user may request that the task be completed automatically. 


Users will have the ability to control the speed of playback and display options. 
They will have the option to undo everything the system did, if necessary. 


1. Many of these situations are research topics that have not yet been worked out. As such, this list represents 
’ ideals that may not be met in the initial implementation. 
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Explicit Scripting by Demonstration 


’ In addition to automatic task recognition, the Pink scripting system will feature 
an explicit, user-initiated scripting capability. 


The Pink scripting system will allow users to explicitly create a new script by 
performing a series of operations while the system records their actions. This se- 
ries of actions, or script, will be stored for subsequent invocation or modification. 


Users will have the ability to restart or disable the recording session. They will 
have the option to abort the recording and undo all operations performed since 
the recording began. This will help give users the confidence to try scripting 
and the tools necessary to restore the system state if they change their mind. 


Effective Visual Metaphor 


feature a visual metaphor fori g and edit- 
ll include the 


script does. The user objects that will be ‘pon or are parameters to 
cript will be readily apparent. A 
¥equire closer examination. 


Using a visual rep 
plored by David C.$ 
munication with a cor 
and learning processes 
gramming systems ar 
features a functional, | i igh- 
.pictorial object-orient 
Both of the 


nterface for the Pink scripting syste has not. 
below are several possibilities: storyboards, fil 


Storyboard Visual Metaphor 


A story board is a collection of cards or pages, each describing one scene of a 
movie or play. It places the characters in the scene and describes their dialog or 
interaction. 


With a storyboard visual metaphor, each frame could represent a discrete step in 
a script. A set of steps ina script (i.e. a procedure or subprogram) could be rep- 
resented by an act. The entire storyboard could represent the screenplay or 
scenario. A program could list the players (i.e. applications and objects) and give a 
synopsis of the play. 


Each frame would have an area at the top that shows where the scene takes place 


and who the players are. At the bottom is the dialog, which could be used to ex- 
plain what is happening or to specify details such as the file being operated 


a ge i ae 
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upon, etc. 
During script execution, the scene currently being executed could scroll by. 


Film Visual Metaphor 


With a film visual metaphor, each frame could represent a discrete step in a 
script. A set of steps in a script (i.e. a procedure or subprogram) could be repre- 
sented by a scene. The entire script could be represented by a movie. 


eee nea ee 
“eB e888 8h 88 


Users could be shown several frames at once and would be able to browse - 
through the scenes in order to get an understanding of what the script does. 
Script editing would be very much like splicing film. 


During script execution the frame would scroll by, as ina real projector. All 
would be dimmed. 


ith a comic visual metaphor, each panel 
A set yi poten in a script (i.e. a prog 


Comics have an inte 
bubble provides a b 
ing what is going on. ° 


¢ Panel sizes indicate relative importance or time requirements. 
¢ Lettering style reflects the nature and emotion of the speech. 
* A wavy-edged or scalloped panel border indicates past time. This might be 


useful to illustrate the environment or preconditions. Other border styles, 
such as a jagged edge, can indicate sound, emotion, or thought. 


A comic strip construction tool called The Comic Strip Factory is available for the 
Macintosh from The Pacific BitWorks. This may be a useful tool for prototyping 
this type of user interface. 


This option would be looked upon with glee by the Japanese and the young-at- 
heart but may turn off corporate America. 
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Object Visualization 


The objects that are used or operated upon at each step of a script will havea vi- 
sual representation or icon associated with them. These icons will be displayed 
to the user when inspecting and editing scripts. 


The visual representation will be determined by the referenced object. The object 
will also be responsible for the granularity of the representation in order to re- 
duce “icon overload.” For example, a standard document icon might represent a 
character, word, paragraph, and chapter in addition to the entire document. 
Even so, these additional details will .be available to the user as necessary. 


Figure 1: Several objé 


may be referenced 


icky selection. 
resented in tk 


he cur- 
lected, the 


The Selection 


Figure 3: The “current selection” icon 


Scripts may also reference a selection set. A selection set references other objects, 
either explicitly or through a user-specified pattern or filter. If the selection set 
contains one object, the current script step would apply to that object. If the se- 
lection set contains more than one object, the current script step would apply to 
each object, in turn. 


2. These and subsequent icons are for the purposes of illustration only. The actual icons have not yet been deter- 
mined. 


en 
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a 


My Selection Set 


Figure 4: A specific selection set document 


Selection sets may also reference selection sets that must be supplied as a param- 
eter when the script is invoked. Users (or perhaps previously-executed scripts) 
would be responsible for specifying objects that belong in this selection set before 
the script can continue execution. The user interface for specifying these objects 
will be the same as when constructing a selection set document. This unspecified 
selection set can be named i in the script so that it may be referenced i i re than 


A Selecti 


Figure 5: A selections en specified 


throwing away a de bj ig | d 
Trash, and one verb, ¢ ; 3 


Hlustrated in E 


move 
My Document Trash 


Figure 6: An example script step using noun/verb syntax 
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Figure 7 illustrates this operation using a declarative style: the same two nouns 


plus one preposition, in. 
je fl 


My Document Trash 


Figure 7: An example script step using noun/preposition syntax ~ 


The style of operation visualization that will be used in the Pink scripting system 
ha determined. There is also a good potential for using animation to il- 


ve been recorded. This 
process or to further cus- 
modification operations 


sers will have the ability to modify scripts one 
ight be to correct mistakes made during thé. 
lize the script. There are s 


Users may add's¢ 2 e 
erations might in é ‘ i 1US- 
es, screen update G 
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Implementation Overview 


Scripts 


The Pink scripting system implementation will include a script object to repre- 
sent scripts and their behavior; a script server providing recording and playback 
capabilities; a script application that will support the script modification and 
playback features; and a task recognition engine to support the automatic task 
recognition and completion feature. 


There are two primary classes that are used to describe scripts: TScriptStep 
and TScript. The purpose of TScriptStep is to encapsulate the information 
necessary to describe an individual script step. The purpose of TScript is to 
collect these script steps and to provide an interface to the recording and play- 
back capabilities of the scripting server (see page 12). 


= 


Script Steps | 


kRedo 


Act ionCode 
Ll void 


virtual TSurrogateTask* GetModelServer (); 

virtual void SetModelServer (TSurrogateTask*) ; 
virtual TCommand* GetCommand () 7 

virtual void Set Command (TCommand* ) ; 


ee 


Script steps consist of an action code (kDo, kUndo, kRedo), a pointer to the appli- 
cable model server’, and the command to perform in the case of a kDo action 
code. 


3. This class definition and those that follow are abbreviated to include only important public member functions. 


4. A model server provides a standard interface to documents see the CHER documents by Arnold Schaeffer and 
Larry Rosenstein. This will eventually be a TEnt ityID instead of a pointer to the actual model server. 
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class TScript : public MCollectible { 


public: 
virtual void Add (TScriptStep*) ; 
virtual TScriptStep* Remove (TScriptStep*) ; 
virtual TiIterator* GetIterator() const; 
virtual void StartRecording(); 
virtual void StopRecording (); 
virtual Boolean NowRecording(); 
virtual void RecordStep () ; 
virtual void Play(); 
virtual void Play (TScriptSteps&) ; 
protected: 


virtual Boer pe ee hoch Eee” Hakescrs peer ce see ver Ur 
= : MakeScriptingClient () ; 3 


following subsections. 


eceiver and Make 
14 gae earn 


Manipulating 


GetIterator return 
Add adds a script step tf 
from the ae > Thes 


ie first script step t: 


theScript; 
Titerator* anIterator = theScript.GetIterator(); 
TScriptStep* aStep = (TScriptStep*) anIterator->First (); 
theScript .Remove (aStep) ; 

theScript .Add(aStep) ; 


Recording 


The process of recording a sequence of commands involves creating a script ob- 

a ject and using the recording-related member functions. StartRecording es- 
tablishes a connection to the scripting server and starts receiving script steps as 
they are performed by the user (see page 12). StopRecording informs the 
scripting server to stop transmitting. NowRecording returns a boolean value in- 
dicating whether recording is currently in progress. 


5. More flexible manipulation member functions may be necessary. 
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Internally, member function RecordStep is called when a new script step is re- 
ceived from the Scripting Server. The default behavior of this function is to sim- 
ply call Add. This function is provided for the convenience of subclassers. 


// Example: Create a script and start recording script steps. 


TScripe theScript; 
theScript .StartRecording(); 


theScript .StopRecording (); 
Playback 


Member function Play with no arguments causes the entire script to be executed 
or played back. Play witha specific script step argument causes only that step 
yed.back,...-hese.functions establish a connection to the Scripting:Server 


TIterator* 
TScriptStep* aS 
theScript .Play (*aS 


r->First ( 


Scripting Server 


ript object or another server such a 


i eg ee 


Commands 


ecognition Engine. 


Recognition 
Engine 


Figure 9: Script recording process 
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The script playback engine facilitates script playback by sending commands to 
the corresponding model server(s). 


C See) ——>| "Bune | LI 


Commands 


Figure 10: Script playback process “ 


Class TScriptingClient provides the primary interface to the recordin and 
5 Pp P ry & 

playback capabilities of the scripting server. This is lower-level interface than 

tha owing direct communication wi iptine 


sublic MClient { 
virtual void sing (TSurrogateTask& 
tepReceiver) ; 

ng (TSurrogateTaské& 
StepReceiver) ; 


Stare’ 


virtual void St 


A second class, 
cording engine. 


eceiver, ] ere- 


class TScriptStepRe 
public: 
TScriptStepR r(TScript 


This class receives script steps from the scripting server as the user performs 
them. RecieveStep is called with each script step, in turn. The default behav- 
ior of this function is to call RecordStep for the script that was specified on the 
constructor, if any. Subclassers may wish to override ReceiveStep to do some- 
thing else. 


The scripting server uses an instance of class TScriptStepTransmitter inter- 
nally to transmit script steps to a script step receiver. 


class TScriptStepTransmitter : public MClient { 
public: 


TScriptStepTransmitter (TSurrogateTask* theScriptStepReceiver) ; 


virtual void’ Transmit (TScriptSteps) ; 


EP eG hi a 
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The constructor establishes a connection to the specified script step receiver and 
Transmit sends the specified script step. 


Receiving Script Steps 


Class TScriptStepReceiver is used to ask the scripting manager to start 
sending script steps as they are performed by the user. This class calls function 
MakeScriptingClient in its constructor to establish a connection to the script- 
ing server and calls function StartTransmitting to initiate the transmit- 
ting of script steps. Function ReceiveStep is called to receive each script step 
the scripting server transmits. Function StopTransmitting is called in its de- 
structor. 


// Example: Subclass TScriptStepReceiver to override member 
// function ReceiveStep to do something interesting and start 


s from the scripting manager. 


: public TScriptStepRé 


virtual void ScriptStep*) ; 


Executing Script 


.,.ocripts or script steps 


TScript theScript; 
TScriptingClient theScriptingServer; 


theScriptingServer.Play (theScript) ; 


// Example: Send a script step to the scripting server for playback. 


TScript theScript; 

TScriptingClient theScriptingServer; 

Titerator* anIterator = theScript.GetIterator(); 
TScriptStep* aStep = (TScriptStep*) anIterator->First(); 
theScriptingServer.Play (*aStep) ; 
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Script Application 


The purpose of the script application is to provide a user interface for recording, 
inspecting, editing, and playing back script objects. 


Record 
Engine 
User C Seript > 
[iertace [= 
Playback . 
Engine 


Figure 11: Script user interface 


e users the ability to create new bjects and 


1g scripts, both during 
ed previously. Itis 


rovide an interface. 
e recording process and for those that have: 
is interface the user will see when a script: 


ack options. Included will 
script without stopping, 


single step, to ex 
¥the user and p 


The user interface for t 
on one of the visual me 


task recognition engine is to 
ser is performing them. This is to 
nition and completion feature (see page 3). 


i 


Script Steps 


Figure 12: Task recognition process 


The task recognition engine receives script steps from the scripting server. It 
compares this command object with recent command objects it has processed 
and attempts to detect a pattern. For example, applying the same sequence of 
commands to each document in a folder, or each card ina stack. This pattern of 
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command objects becomes a script that has been implicitly constructed. 


When the task recognition engine detects a repetitive command object pattern, it 
will highlight the user actions that cause the next command object to occur. This 
feedback will demonstrate that the system is anticipating the next user action and . 
has potentially constructed a script to perform the task. 


The task recognition engine will include options to save the implicitly-generated 
script and to begin execution of the script in order to complete the user’s task. 
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Application Scenarios 


There are several applications or uses for this scripting technology. These in- 
clude task automation, interactive examples, procedural annotations, and appli- 
cation customization. These are determined, in part, on how and where a partic- 
ular script is made available to an end-user. These options include implicit 
scripts, document scripts, embedded scripts, annotation scripts, and bag-on-the- 
side scripts. 


Task Automation 


Implicit Scripts 


Some scripts are generated implicitly by the scripting system and may be in 
ete a repetitive task (see page 3). ee 


ing every document in a fal 
to replace one phrase wi 
hice for the system to 


yer. After the first 
d complete the 


desktop objects? 
other desktop object 


Another example use 
haps one that is infreq 
be automated complet 


Open a rolodex-li} 


‘he script could firsi 
ser t appropriate inform 


er the user indicates that the step is complete, t pt could close the 
rolodex, open an invoice program, and ask the user to enter the billing rate 
for this client, and then pause. 


¢ Other steps might include setting up file folders, printing a “welcome” letter 
with a personalized message, adding a reminder in an alarm program, and 
so on. Some of these steps the script could perform automatically and others 
it might pause while they are completed by the user.’ 


Another example use of a script document is to retrieve electronic mail messages 
froma remote system. The steps involved might be: 


e Lauch a communication program 
¢« Opena connection to the remote system 


6. Thanks to Frank Leahy for this scenario. 
7. It would be nice if the user could perform the steps in a random order, much like a check list. 


eR a a tae at chee re SP er ce een ee 
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Log on 

Open a file to receive the email messages 

Send the commands necessary to retrieve the messages 
Log off 

Close the connection 

Quit the communication program 


Interactive Examples 


Embedded Scripts 


Scripts may be embedded in a document to perform some action. This embed- 
ded script could be invoked on one of several conditions. For example, the script 
could be selected and invoked at the option of the user. Or, it could be invoked 
automatically. whenthe-pertien of the document to which it is attached:is:visible. 


reisina help system. W 
1, the help system could 
could also contain a: 
watches, pauses, and.t 


Procedural An: 


similar to sta 
directly. 


The author coul 


Application Cus 


Bag-on-the-side Scripts 


easks for help 
essage explain- 

” script that performs 
tically undoes any 


an un- 


Scripts may also be used to enhance or customize the features of an application. 
These scripts are similar to embedded scripts as described above, but are at- 
tached to an application menu or button instead of adocument. This script 


might be defined to apply to the current selection. 


An example use of this feature is to change a drawing tool to a pre-defined con- 
figuration ina paint program. The script could set the tool pattern, color, size, 


shape, enable the grid, disable mirroring, and so on. 
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Dependencies 


_ There are several dependencies suggested by this system. Many of these depen- 
dencies regard selection sets, command objects, end-user objects, and user inter- 
face issues. 


Selection Sets 


Scripts must have some method of referring to a persistent set of selections. 
These selections may be anchors (sticky selections) or may be normal selections. 
The script will be applied to each selection in the set, in turn.8 Some require- 
ments for selection sets are: 


‘Users'must havea way'to save selection se fe 
in a selection set document. 


either in the script or 


must have a way to indicate a at must be specified by 


at script invocation time 


Command Obj 


Command objé 
user actions. Scripts 
uments when a scrip 


e Command objects t 
an icon or a string 5 Wi i i yr ed- 
iting a script. 


pproach 
the command object to be invoked. 


e During the task recognition process (see page 4), identical commands that 
are being applied to different objects must be compared in order to deter- 
mine the iteration pattern. One approach is to require command objects to 
provide comparison and iteration functions to the scripting system. 


End-User Objects 


End-user objects are things that end-users can manipulate. Included are desktop 
objects such as applications or documents, a paragraph of text within a docu- 
ment, a graphic in a drawing program, and so on. Some requirements for end- 
user objects are: 


8. It is not yet clear whether the entire script or just the current script step (which might be an invocation of another 
script or sub-script) should be applied to each selection in the set. 
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¢ End-user objects must know what command they support. The scripting 
system will use this information during script editing and to provide 
diagnostics. 


User Interface 


There must bea standard way of indicating an anticipated user action. This 
could be a color or some other form of highlighting. 


During the script recording process, users could be asked to clarify their intent. 
For example, when they make a selection, the system could ask whether they 
meant that particular object, the object at that location, etc. The acceptable level 
of “intrusion” must be determined. 


Bag-on-the-side scripts require that the user be able to attach a script to an 
application’s user interface. This could be on a menu ora custom button. This 
met ibility has yet to be determined. 
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Donner Party 


Because collaboration isn’t all 
sweetness and light. 
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Sometimes it’s dead serious. 


Jack “Too Damn Fat” Palevich 
x4-4738 AppleLink: PALEVICH1 
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What is Collaboration? 


“collaborate — To work together, esp. ina 
joint intellectual effort.” 


— The American Heritage Dictionary 


Collaboration is what people do when they work together to achieve a common goal. Most 
kinds of work require a great deal of collaboration. People's work days are made up of periods 
of individual work, interspersed with meetings, mail, phone calls, chance encounters, and 
other forms of collaboration. 


Collaborative activitie 


Real-time er on the same thing a 


Long-term Peo 


When computers are added to'th 


Centralized All the work is do 


Distributed The work is done 


hich will be possible in the 


Post-it Notes 

Classroom Administration 
Desktop Sharing 

Document Sharing 

Shared Whiteboard 

Group Decision Support System 
Network Administration 
Version control, undo 

Mail 

Personal AppleShare 
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To date personal computers have primarily enhanced people’s individual work. Collaborative 
activities are still carried out pretty much by hand. For example, while people use word 
processors to write documents, the resulting documents are usually passed around in printed 
form. People scribble comments on the margins of the documents, then return them to the author. 
The author collates the comments, then laboriously edits them into the original document. The 
document is printed a second time, and the process repeats itself. 


Pink is going to change this, because collaboration is built into the very fabric of Pink. Pink 


provides an environment in which people can collaborate with ease while retaining their 
privacy, their dignity, and their sanity. 


Uses of Collaboration 


Collaboration is something people already do. They just don't get much help from their 
computers. Pink is going:to:support: both:real-time and long-term collaboration. : 


Examples of real-tim 


Example 


Remote access A single user using a remote re 


Administering a remote file 


Remote assist 


Micro meetings 


Examples of I 


Example Description 


Document review comments _ People type review comments into the original document. The 
author can accept or reject their suggested changes. It the 
author accepts their change, the system automatically 
updates the document. 


HyperText links Groups of documents can be hyperlinked together. 


Source code sharing Large software projects are easier to create & maintain 
because of automatic version control. | 


Tam thinking of HOOPS here. 


@ Registered /Restricted Collaboration Toolkit March 15, 1990 2254 


Why a Toolkit? 


“Intuitions about collaborative work seem to be 
uniformly incorrect.” 


— Tom Erickson, Human Interface 
Review 


If collaboration is such a great idea, why not just implement a universal collaboration 
application and be done with it? Well, unfortunately, there seem to be almost as many kinds of 
collaborative applications as there are people writing them. This is because people work 
together in so many diff ‘orce all forms of collaboration intQ..a 
mold, we provide a to } write collaborative appli 0 


The Collaboration T 


users to shift smoothly from One: 


¢« Responding toa 
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e Leaving a voice mail m 
their phone. (The shift 

Q nding a mail messag 
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How Collaboration is Built into Every Pink 


How is this done? It’s done by modifying the traditional user-interface loop to include multiple 
users. The parts of the Pink system which enable this to happen are: : 


* The Document Architecture (Cher) 
* The Event Server 
* The Graphics Library (Albert) 


This means that al] dé 
between several peo 
will be Providing a k 


a even the Desktop itself cant 
king this kind of col 


computer time ¢ 
will center aro 


entire desktop. This allows the §roup to share essentially all applications, whether Or 
ta 


not the applications use the Cher documen rchitecture. 


2When | wrote MeerKat, my Blue screen sharing program, [ asked Apple engineers what applications 
they use. It turns out that engineers use text editors, Program sb ..i*, and drawing Programs. First level] 
Managers use presentation software and Spreadsheets. Second-level mangers use AppleLink, (Of 


Wo to twelve people. It takes two to tango, and twelve people make up a jury. 
Continuing the food analogy, the Finder is the Dread & cereal group, desk accessories are ‘lie: & 
vegetables, and §ames could be the desert. 
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Desktop level collaboration gives the group access to the entire desktop of the shared machine. 
This is especially useful for the remote-assistance scenario, where one user is trying to debug 
another user's machine. 


Real-time Collaboration 


Real-time collaboration in Pink is based on the “what-you-see-is-what-I-see" model. This 
means that each collaborating user sees, as much as possible, the same display as all the 
others. This gives the group the illusion of actually sharing the same physical document. 


Of course it is not always possible to attain this ideal. For example, consider the following 
case: One user has a color display and another user has a monochrome display. The two users 
are sharing the same document, and the document happens to have a color picture. The color 
picture will show up as.a.grey-scale.picture.on.the.monochrome screen. If the user on the.cole: 
screen says "Look at th h the monochrome screen will net 

tell which flowers are 


ique is to have 
fOMe screen will see 
abilities which are 
‘on all of the 
monochrome 


There are several wa 
the user with the coh 
which flowers are 
not present on all ¢ 
machines, the pic 
machine. 


round their problem, 


cted. Another technique would be to a 
e inachines In this case, since color is. 
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Desktop Sharing 


In order to understand how desktop sharing is implemented, it is necessary to understand the 
human interface loop. This loop is what binds the users and the applications together. The 
loop begins when the application makes drawing calls to Albert. Albert tells each of its 
GDevices to draw. The GDevices then draw in their associated frame buffers. The user sees the 
display, and moves the mouse. The mouse notifies the event server. The event server sends a 
stimuli to the application, and the loop is complete. 


an | 


The Application 


Graphics 
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In order to allow multiple users to access the same application, we have to splice into the 
human interface loop. By splicing into the loop at the level of the dotted line, we can provide 
desktop sharing without affecting the application at all, and with only minor modifications to 
Albert and the Event Server: | 


“A 


The Application 


Remote 
Desktop 


Event Server |. 


Document Sharing 


When the application is written to use Cher, it can be used in real-time document-based 
collaboration. This is because Cher cleanly separates the data (called the Model) from the 
commands which modify the data. To share a document we run copies of the application on 
each user's machine. Each user's machine acquires a cached model, which contains a copy of 
the original data. When a user does something, their action is encapsulated into a command 
object. The command objects are sent to the model server. The model server distributes the 
command to all of the other collaborators. In this way all of the models are kept in sync.® 


like my MeerKat and Farallon's Timbuktu. 
6See the Cher Document Architecture for more details. 
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Model Model 


ModelServer ModelServer ' Cached Model 
Document Document Beer ; 
| 4. iy 
Presentation Presentation : 
Presentation 


Since Cher deals with changes to docum 
means that Cher does not deal with trac 
visual feedback of tracking, we will hav 


Distrib 


Tracking is 
of tracking inc 


¢ Defining a line by clicking and dragging 
e Scrolling a window 
¢ Typing text 


Tracking is divided up into three phases: 
1) The start, where tracking begins. 


2) The middle, where tracking continues. 
3) The finish, where tracking ends. 


The middle phase lasts as long as the user is performing the action. It is during the middle 
phase that the rubber-banding of the line occurs. 
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To faithfully reproduce tracking across the network, it is necessary to transmit the start phase, 
as much of the middle phase as possible, and the finish phase. The middle phase can be 
transmitted asynchronously, using protocols which do not guarantee delivery of information. 
This is because lost parts of the middle phase do not affect the outcome of the tracking, and the 
remote users are usually more interested in viewing the current state of the tracking than its 
exact history. 


The Whiteboard 


By default, Pink applications are not aware that they are being controlled by multiple users. 
Whiteboard is an experimental Cher—based application which is directly aware of multiple 
users. Whiteboard is designed to assist small groups in their collaborative efforts. It acts as a 
cross between a white-board and a bulletin-board. A Whiteboard document is a shared space 
where users can jot down.their.ideas, leave.clu boards ang documents for one another or engage: 
in mini-meetings. It is: 7 
and Gregg Foster's Co 


The Whiteboard app 


: is shared MacDraw. 
Finally, it should enid'up as a rototype distributed component 


7Cognoter was written at Xerox PARC. 
é 


Sc Na i i 
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A Collaboration Toolbox 


This section describes the objects, classes and servers which support collaboration. Taken asa 
whole, this is the Collaboration Toolkit. The careful reader will note that many of the things 
described here are actually implemented by other parts of the Pink system. 


Some of the following items are very concrete — they describe things which are already 
implemented. Other items are more abstract — they are place holders provided to stimulate 
discussion.8 


Users as first class oe 


or at least know how & 
includes things like: 


nterests, history 
ices / customizations 


Once we start keeping information’a 5 
hope to provide appropriate access c 


issues arise. 


Groups as first class objects 


fay to deal with gr 
out, information abo 
they can receive mail and ow 


It might be useful to allow groups of other network objects, like printer poo s or server pools. 


Network Shareable Resources 


Network shareable resources are things which can be shared over the network. These include 
hardware resources, like printers, and software resources, like data bases. Pink provides the 
basic technology to allow these resources to be shared. Hardware resources can be shared via 
the network-transparent client & server classes. Software resources can be shared either via 
servers or via copying. 


8 if something in this list doesn’t jibe with your expectations, please tell me. Jack Palevich (x4-4738) 


tt seems likely that the TPerson, TPeople, and TNetworkShareableObject classes will all be subclasses of 
the NetComm Tldentity class. 
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Some typical shareable hardware resources are: 


¢- Computers 

e Printers 

¢ Video equipment 
¢ Modems 


Some typical shareable software resources are: 
¢ Data bases 
¢ File systems 
e Fonts 


e Applications 


Butlers 


In times past it was cc 
stereotypical butler yw 
scenes, ensuring th 


ploy butlers to run thei 
g person who move 


Mot provide butlers. Asa’ 


ee nthe 
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The Address Book 


Pink will have a way for both programs and users to find the objects used in collaboration. This 
will be something like today's Chooser, only much better. The exact details and capabilities 
are not yet determined. In general, the following kinds of ideas are being considered: 


¢ The user-interface should look something like the one used to manipulate 
files & folders. 

e It should be possible to browse the space of all entities. 

e It should be possible to search for entities. - 

* Once an entity is found, it should be possible to cache an alias to the entity 
in a private address book. 

e Interesting information will be associated with an entity. It will be 
possible to view this information and use it as a key for sorting and 


made great progre it heir ADAS10 


It is necessary 
the Apple Ma 
their ADAS system. 


Contact Logs 


The Collaboration Toolkit will keep track 
It will be easy.for:users to browse and reco 


Issues 


There are a number of issues which need to be resolved. Many of these are policy issues. We 
will have to conduct user tests, surveys, and other experiments to decide upon the right 
policies. 


Sharing Resources 


Resources are things, like documents, fonts, and applications, which are used during a 
collaboration. While the data in a document must be shared, it is necessary to ensure that all 
users have the right fonts and applications. 


104 pple Distributed Authentication Server 
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It’s easy to determine which resources are needed for a collaboration, and it’s easy to check if 
each collaborator has the necessary resources. The issue is what do when some users lack the 
necessary resources. 


One policy is to force users to provide their own copies of the needed resources. 


Alternatively, it is possible to borrow the needed resources for the duration of the 
collaboration.!1 12 Borrowing raises many questions: 


e¢ Can we ensure that it is truly a temporary borrow? (Guilt and its uses in user 
interface) 

e Will Font vendors go for it? 

e Will App vendors go for it? 

¢ Can we support site-licensing ? 

° seo we lend mogeunent Miewero? What about document editors? 


yng—term collaboration, or just 


Borrowing solves 
harder problem % 
to user. What sk 


d. We run intoa 


One alternative is to provie 
In some cases, though, this can’ 
things. To reduce confusion, it should 
common-denominator” mode, where thé 
machine. 


11 In the case of fonts, this is very similar to what is done when a document is printed ona printer: any 
fonts the printer doesn’t already have are downloaded to the printer along with the document. 


_ 12The USA project investigated sending both instance variables and methods across networks. It will be 
interesting to see how applicable their work is to this problem. 
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Some strategies for working around differences in hardware are listed below: 


Virtual memory (although this could lead to thrashing) 

Scaling and/or scrolling when viewing a large screen from a small one 
Gray scale (or Black & white dithering) substituted for color 

Dropping frames from an animation 

Representative frame substituted for video 

Degradation of sound (Stereo to Mono, sampling rate reduction, delays) 
Placeholder objects (Rectangle which says “I am a pipe”) 

Distributing the results of a computation rather than duplicating the 
computation on each machine. > 


Internationalization 


Collaboration adds a new dimension to internationalization issues. This is because the 
individuals involved inacollaboration: might: bewwsing different languages. It would b 
desirable to have errot nu text appear in each user’: 1 


Desktop sharing also: 
a different languag: 
provide remote ass 


trying to use a particula 
would happen if an A 


ser tried to 


nce to a Japanese user. 


How fast etwork have | 
Real-time colla 
the collaborate 


sufficient for applications which do’ 
reach of all Apple network mediums, 


Document sha 
available locally: 
setup time from the receivers. 


In some situations real-time sharing will be impractical. In these situations we can fall back to 


another mode of sharing: facsimile transmission. Users can collaborate by mailing each other 
screens, windows, and documents. 


Leaving and rejoining a real-time collaboration 


It takes some effort on part of the users and their machines to establish a real-time 
collaboration session. It would be nice to save the state of a session so that the users can continue 
long-term collaboration and resume real-time collaboration. 
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We have to decide what should happen if a machine or network involved in a collaboration 
should fail. In general it should be possible for the surviving collaborators to continue the real- 
time collaboration. 


If the network is partitioned, it is possible that two independent groups of collaborators will 
result. Under the Cher document architecture, at most one group will have access to the model 
server. That’s the group which can continue the real-time collaboration. 


A user who is cut off from the model server could have the option of saving the cached model. 
This would create a new branch of the document. : 


Human Interface Issues 


There are a number of 
them is to go out and 


ted to collaboration. The only way t 


Long-term, 


Privacy, secu 


Privacy should | 
have access to e 
their machine. 
access. 


But what about educational setting 
policy for a machine. 


Do we force people to log into their own ff 
password? What happens when they forg 


Access control lists 


We need to allow selective access to documents, files, applications, and all other shareable 
resources. Whatever style of access control is decided upon, it should be consistent across as 
many different kinds of shareable resources as possible. 


13The Apple Mail project is experimenting with the idea of “keys”. A key provides authorized access to a 
service. Keys are icons which can be put on the desktop, stored in folders, given to other users, and thrown 
away. Just having a key is sufficient for using a service — you don’t have to drag keys into locks. 
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People, group, & resources look & feel 


People, groups, and other shareable resources should all be some sort of icons. People should 
look like little head&shoulder photographs of themselves. (What about Islamic countries, 
where they disapprove of representational art? Do they use ID Photos in-their passports?) 

Groups should look like containers. 


Shareable resources should be found and manipulated in the Finder. 


Versions and branches of documents 


When people work on a document over time, they create versions and branches. The major issues 
raised by versions are actually orthogonal to collaboration, and so fall outside the scope of this 
document. The HOOPS 
access control. 


Shared documents of the version 


architecture. 


See the HOOPS pr r more details. 


Real-tim 


Remote Mo 


Ideally, each user should see the po 
should act just like the users own poin 
faces so that the user can tell the state of: 
belongs to which user. 


i tell which 


Since smooth..pointer motion is aaaaed 
e users’ pointer 


oved more jerki 


If it is not pose rge number of pointers, some altern 
remote users’ pointe ts will be required. At the very least the. belonging to the 
user who is in control should be clearly visible to all collaborators. 


Butler look & feel 


Butlers mediate between users and the outside world. The word “butler” conjures up a middle- 
aged formal servant. This might not be the best user interface. It isn’t entirely clear if an 
anthropomorphic agent is required at all. Prototyping and user testing is required here. 


- 14annette tells me that only programmers call these things “cursors”. 
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Turn Taking 


As far as the ordinary Pink application is concerned, there is only one thread of control. The 
real-time collaborators take turns being the “real” user. 


There are many ways of taking turns. We must decide upon one which is low-overhead, but 
which isn’t confusing. It may be necessary to offer a range of turn-taking policies, so that the 
users can choose the one which best fits their needs. Some possible policies are: 


e Free-for-all | 

e Robert’s Rules of Order 
¢ Teacher & Students 

e Baton Passing 


Calling meetings: 


Involves: 


nd other shareable 


allowing them to respond 
sathering them into the collaboration 


During a real-time collaboration we wa 
all in the same place. This is why we pr 
should also ee. for voice and video. 


4d collaboration. 


Voice digitizers, such as Farallon’s MacRecorder may be good for annotations and voice-mail, 
but unless they can be used continuously in real-time they are not useful for real-time 
collaboration. 


Video conferencing is harder to provide, because of processing and network bandwidth 
limitations. Never-the-less, we are already seeing experimental local-area-video-networks 
being installed to provide video—-conferencing and to aid production of multi-media documents. 
Where these video networks are available it makes sense to use them for real-time 
collaboration. 


Unsynchronized vs. synchronized views 
Document sharing allows different users to view different parts of the same document. But once 


users are looking at different things, they may find it hard to return to a common ground. We 
will have to experiment with unsynchronized views to see if people can understand them. 
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Window Frames 


When a document window is shared between several collaborators, we want to have some 
visual indication that it is shared. One suggestion is to put the user’s faces in the title bar. 


Inter-operability 
"No man is an island, entire of itself; every 
man is a piece of the continent" 
—John Donne 


Pink users will need to collaborate with people who do not have Pink machines. We must make 
this as easy as possible. 


iat kind of machine the other 
From an inter-operab four kinds of people a Pink: 
collaborate with: 


Kind of User Description 


Another Pink use ork. When Pink 


This is the easy case. Everyt : 
might have trouble 


on several machine a 
ing application obje 


A user of ano 
collaboration 
product (e.g. Blue, A/UX 
Newton) 


document 
«. possible, 


A user of another brand of is is e der tha 
computer (e.g. VAX, Cray) i-time collal 


4ve can't send therm 


A person : 9 
voice, and video m 


any compu 


What about different processor architectures? 


Pink is designed to run on many different processor architectures. This means that Pink 
collaboration has to work between users who are using different processors. 


Desktop sharing is easy between different processor architectures, because only the data is 
transmitted. 
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Document sharing is easy if versions of the same application are available for each 
architecture. Application borrowing is harder, because application binary files usually are 
targeted to a single processor architecture. Application borrowing would still be possible if 
applications were distributed in AppLex}5 style intermediate code. 


Support for other styles of collaboration 


Pink is designed primarily for the "knowledge worker". For that reason, the user interface 
supplied with Pink supports peer-to-peer collaboration. There are many other types of 
collaboration, and Pink should allow them as well. By keeping the lower-level classes as 
policy-free as possible, it should be possible for third-party developers to support other styles 
of collaboration. 


might want to build su 
we will try to leave t 


Style of Collaboratio 


dent's machine. 
ng to all the 


Teacher / Student . The teacher can completely rea 
The teacher often needs to do £ 


dents’ machines at once. 


Parent / Child 


Area Associate / Group 


More than one User per 
Machine 
than we 
imple 


Public Compute y 
with access to personal computers. be 
up a Pink machine so that certain activities S Gack as deleting 
applications) are restricted. 


15 A ppLex is Wayne Loofbourrow’s experimental processor-independent object code. At the moment 
Applex programs run at about 1/4 to 1/2 the speed of native code. 
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Dependencies on other Projects 


"You've got to have friends.” 
—Bette Midler 


Collaboration works in Pink as a result of cooperation between a great many independently 
developed pieces of hardware and software. One of the reasons for writing this chapter i is to 
bring all the interdependencies out into the open. With all of the pieces laid out, it is less 
likely that some vital capability will go unimplemented until the last moment. With all the 
issues enumerated, it is less likely that some vital issue will go unresolved.1é 


Related parts 


Cher 


The "C" in the acr 
direct support fro} 
document-based 


"Cher" stands for "Collaboration". It's 
the document architecture, it would be im: 


e, too! Without 


Albert 


Albert is the d ie 
collaboration by allowing peopt 
images. In addition to device indepe 
support real-time collaboration. Fortuti, 
features needed to support printers and 


Albert's ability to add and remove GDevic 


commands over the. n tothe other machine. In this way, everythin wn on the shared 
screen is also drawn on the remote screen. 


Font borrowing is accomplished in collusion with Albert's font manager. 


lore you're an implementor of one of the projects mentioned here, and you don't think your project will 
supply the listed capabilities, please say so! If we're assuming too much, now is the time to tell us, so we 
can figure out what to do about it. 
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Multiple pointers greatly enhance the utility of real-time collaboration.!” Each user controls 
one or more pointers. Even if only one user can edit the document at a time, the other users still 
need to be able to point and gesture. In addition, it should be possible to adorn pointers. 
Adornment adds information to the pointer image. The two major adornments we need are: 


e Drop shadows to indicate remote mouse-button state. 
¢ Little pictures which indicate pointer ownership. 


It is worth noting, in passing, that screen sharing technology is very similar to screen recording. 
and playback. This means that it should be very easy to support "video-tape” style help. 


NetComm 


me 


The network is the mai 


between Pink machines. This 
the quality network 


llaboration. Some specific thi 


Ss & servers 


cure Password authentication 
secure protocols 

falticast protocols 

Browser 


Events 


Re ac ing 
¢ Simultaneous tracking feedback in multiple views 
e Tracking across view boundaries 

¢ Tracking with more than one input device at the same time 


Hopefully all of these features can be added in a clean, understandable fashion. 


17Dan Venolia's Toy Box program is a compelling example of multiple pointers. It is a 3D collaborative 
environment. Each user has a 3D pointing device they use to create and manipulate blocks. All users are 
creating blocks in the same space, and all of the users can see each other’s pointers and blocks. Two 
users can cooperate to change the size of a block by grabbing at opposite corners of the block and pulling. 


5 tg Sens Sa a sk ee ee 
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Finder 


The Finder provides all the user interface for starting collaborations. Specific features include 
support for: 


* Finding other users 

* Starting collaborations 
¢ Rejoining collaborations 
¢ Browsing Versions 


Related Non-Pink efforts 


Project 
Apple Mail 


AppleShare & FileShar 
Diet Coke 


Spider 


control. 


Chorus A suite aborative wo 

BlipVerts ® “based mail & document: 

Newton llaborative component document architéctur 
network protocols. 

Medley A collaborative HyperMedia editing concept system. 


181¢ your project isn’t on this list, it’s because I haven’t heard of you. Please drop mea line at 
PALEVICH1 or x4-4738. 
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Dependencies on hardware 


So far we have discussed how collaborative software. Several hardware projects have the 
potential to greatly aid collaboration, too: 


Project Application 

Sound I/O and Signal Voice—-conferencing 

Processing : 
Audio Notes 

Telephone interface Voice transmission 
Answering machines 


Fax interface 
Video I/O 
Fast networks 

Digital video conferencing 


Haring large documents 
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Laser .. 


i 

e 
7 
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The Pink Layer Server 


Larry Rosenstein 
M/S 77-A X4-8123 


Architecture 


The function of the Layer Server is to divide the available screen area among all the applications that are 
running. You can think of it as a system-level window manager. (The View System would be the appli- 
cation-level window manager, since it manages the screen space within an application's layer.) 


The direct clients of the La 
adapters.) In the Pink war 
Toolbox includes a TLay. 
the Layer Server to impl 


apters. (Applications, in turn, 
“Pink Adapter.” The View.S 
layer in the Layer se ; 


Clients request screen Space by creating a TSystemLayer object. To £ TSystemLayer represents 
an actual layer; when;:that object is is deleted, the layer is also destroy 
other classes (describ ha e used to refer to ane 


The Layer Server 
those behind it. Th 
tent minus the uniOn' GEthees 
The layer ordering is determined by three 
respect to existing layers. 


Finally, the layer 
clicking ona layer: j : 
ing ona layer brings itto the front-of'its category of layers. (Note that the Tayer does not necessarily come 
to the very front of the layer list; layers in other categories might still obscure it.) 


lt is also possible to programmatically bring a layer to the front of its category. (See the description 
below.) 


Each layer contains a TSurrogateTask object, which is the task that “owns” the layer. The owner of a 
layer is the task that receives events for the layer. These events include mouse down/up, key down/up, 
and activate/deactivate events. 


Key events are special because the keyboard (and similar devices) are non-positional. (In this paper, 
“keyboard” refers to all kinds of non-positional devices.) The target of keyboard events is determined by 
the state of the system, rather than the state of the input device. The Layer Server keeps track of the layer 
that gets these events. 
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The algorithm the Layer Server uses to determine the keyboard event layer is very simple, but seems to 
work for the typical cases. This is one area in which we need additional thought. (See Open Issues at the 
end of the paper.). 


Only two kinds of layers can receive keyboard events: document layers and floating windoids. 
Document layers always receive keyboard events, while windoids may receive keyboard events. When 
the client creates a layer it specifies whether it can handle keyboard events. Internally, this flag is forced 
to TRUE for document layers, and FALSE for all other layers except windoids. 


The Layer Server maintains the keyboard event layer using the following rules: : 
* If a layer is created or made visible, and it handles keyboard events, and it is in front of the cur- 
rent keyboard event layer, then it becomes the keyboard event layer. 


* If the user clicks in a layer, and that layer handles keyboard events then it becomes the key- 
board event layer. 


« If the keyboard 
the keyboard e 
keyboard event 


As mentioned earlier, tf ystemLayer represents the actual layer, in 
matches the lifetime 6f the layer. The Layer Server also provide 
lternate.“"names” for the same layers. : 


hat the lifetime of the object 
refer to existing layers. 


tween TLayerAlias and TSystemLayer are 
refer to different layers in its lifetime, and @ 
attecting the actual layers on the screen. 


ing the task owning a | a ias : he fol- 


SgIONS of the layer 


The Layer Server arbitrates between layers by computing a visible region for each layer. Clients are re- 
sponsible for getting the visible region and clipping all their drawing to at least that region. TLayerAlias 
(and TSystemLayer) maintain a seed to indicate when the visible region has changed. Clients can use this 
to take action only in the event of a change in the layer’s visible region. 


Since the Layer Server accepts requests from many clients, there must be some concurrency control to 
prevent any one client from using an out-of-date visible region. (The effect of this would be allow one ap- 


plication to trash the windows of another application.) 


To implement concurrency control, the Layer Server creates a global drawing semaphore. When the 
Layer Server needs to update the visible region of any layer, it acquires the semaphore in exclusive mode. 
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Clients, using a method of TLayerAlias or TSystemLayer, acquire the semaphore in shared mode before 
retrieving the visible region, and therefore before drawing. 


This protocol ensures that the Layer Server will not start recomputing visible regions until all its clients 
are through drawing, and that no client will begin drawing until all the visible regions are in a consistent 
state. : 


Client Interface | : 


Global Types 


typedef unsigned 
const LayerID kIxr 


#5 one value that is 
n’t be a problem.) 


LayerID is a unique ID; 
never assigned. (Unless 


typedef enum 


kDesktopLayé” 


LayerKind is used to describe the category 6 
pull-down and popup menus, alerts, torn off 
the desktop. 


and 


typedef e; 


LayerPosition is used. ae 8g 1: es ack of its 
layer category. 


TSystemLayer 


TSystemLayer is the client’s interface to the actual layers. The lifetime of the object matches the lifetime 
of the layer on the screen. 


TSystemLayer(const TWorkRegion&é itsExtent, 
TEventServer&é anEventServer, 
const TSurrogateLayer& behindLayer, 
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| 


Boolean handlesNonPositionalEvents = TRUE, 
Boolean isVisible = TRUE); 


TSystemLayer (const TWorkRegion& itsExtent, 
TEventServer& ankEventServer, 
LayerPosition itsPosition, 
LayerKind itsKind, 
Boolean handlesNonPositionalEvents = TRUE, 
Boolean isVisible = TRUE); 


Create a TSystemLayer, which results in creating a physical layer. 


Parameters: 
itsExtent The desired extent of the layer. 
anEventServer The ‘ OMe of the oe the task that receives the yen s events. 
itsKind heking 


handlesNonPosition 
events. This 
Kind is kDocument- 
orced to False. 
isVisible 


The different construs 
you pass a TSurrog 
is not of the same ki 
layers.) 


respect to existing layers. If 
(If behindLayer 
ategory of 


f tind, then the new la! 


y of 


~TSystemLayer () ; 


Destroy a TSystemLayer, which also destroys § 


Get the unique ID associate with the layer. This may be useful for creating another object (e.g., TSurro- 
gateLayer), or if you want to pass the LayerID to another task. IsValid returns True iff the Layer ID is not 
kInvalidLayerID 


void GetOwnerTask (TSurrogateTask& ownerTask) ; 


Copy the task owning the layer into ownerTask. 


void Hide (); 
void SetVisibility (Boolean makeVisible) ; 
void Show(); 
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These methods hide and show a layer. Hide and Show simply expand to calling SetVisibility. 


void SetExtent (const TWorkRegion&, Boolean addToUpdate); 


Set the extent of the layer. addToUpdate specifies whether any new area belonging to the layer should be 
added to the update region of the layer. (Clients might pass False if they planned on immediately 
updating the new area.) 


void AcquireDrawingSemaphore({) const; 
Boolean DrawingWaiters() const; 
void ReleaseDrawingSemaphore() const; 


These methods deal with tk 
quireDrawingSemaphore 


ftained by the Layer Server. Clier 
etVisRegion, or GetVisRegion$Se 


e drawing in the layer, bracket drawing 


ase DrawingSemapha: 


Since client must get th 
with calls to AcquireDr, 


void TWorkRegion& updat 


Set updateRegion t¢ layer. This also 


void 


Set visibleRegion to the visible region for’ 
fore getting the visible region, to ensure that. 
set of visible regions. 


the visible region. *¥ ’ 
time you checked. You must ¢a cquireDrawingSemaphore before before g visible region, to 
ensure that the Layer Server isn’t in the process of recomputing a new set of visible regions. 


operator TLayerAlias() const; 


Create a TLayerAlias object from the TSystemLayer. A TLayerAlias provides a way to refer to a layer and 
fully manipulate it without affecting whether the layer is Geetoyec or not. A TLayerAlias object can be 
flattened and resurrected, while a TSystemLayer object cannot.” 


1. If necessary, we can make clearing the update region an option to the call. 


2. The reason is that you don’t want to have two insances of TSystemLayer that refer to the same physical layer. 
Perhaps this is not a useful restrictions, in which case, we might be able to eliminate the TLayerA Lias class. 
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operator LayerID() const; 


Return the LayerID of the layer. This is a convenience? operator so that you can pass a TSystemLayer to 
functions that take a LayerID. 


operator TSurrogateLayer() const; 


Create a TSurrogateLayer from the TSystemLayer. 


long Hash() const; 
Boolean IsEqual(const MCollectible* otherLayer) const; 


Overriden methods from MCollectible 


TLayerAlias 


TLayerAlias provide 
the layer is not tied t 
and sent to anothe 


nce is that the lifetime of 


ie same capabilities as TSystemLayer. The 
: ayerAlias can be flattened 


e lifetime of the TLayerAlias object. Ani 
in.then manipulate the layer. 


The interfaces be 


TLayerAlias (é¢€ 
TLayerAlias (cof 


Assign one instan 


void SetLayerID(LayerID itsLayerID); 


Get and set the unique ID associated with the object. 


TStreamé operator>>=(TStream&) const; 
TStreamé& operator<<=(TStreamé) ; 


Flatten and unflatten operators. 


3. In truth, it’s a convenience for me. I can write methods that takea LayerID, and you can pass a TSystemLayer or 
other kind of layer object. | don’t need to overload the methods to take botha LayerID and layer objects. 
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TSurrogateLayer 


TSurrogateLayer provides a simple reference to a layer. You cannot manipulate the layer, but you can ac- 
cess some Of its attributes. 


The interfaces below list only the method ot TLayerAlias that aren’t in TSystemLayer. 


TSurrogateLayer(const TSurrogateLayer& otherLayer) ; 
TSurrogateLayer(LayerID itsLayerID = kInvalidLayerID) ; 


Create a TSurrogateLayer f 


bject, or froma Layer unique ID. 


LayerID 
Boolean 


with the layer. This may be useful for cre 
to pass the LayerID to another task. IsVali 


st object (e.g., TSurro- 


Get the unique ID assog¢ 
ue iff the Layer ID is not 


gateLayer), or if you wa 
kInvalidLayerID 


void 


Copy the task owning 


void SetLayerID (Laye 


Flatten and unflatten’ 


long Hash() const; 
Boolean IsEqual(const MCollectible* otherLayer) const; 


Inherited methods from MCollectible. 


operator LayerID() const; 


Return the LayerID of the layer. This is a convenience operator so that you can pass a TSurrogateLayer to 
functions that take a LayerID. 
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TSurrogateLayerServer 


TSurrogateLayerServer provides access to several global functions of the Layer Server. These are func- 
tions that apply to the layers as a group, rather than an individual layer. 


Boolean HandlePositionalEvent (const TGPoint& location, 
TSurrogateLayer& clickedLayer, = 
Boolean& causedLayerSwitch, 
TSurrogateLayer& oldFrontLayer, 
Boolean& causedFocusSwitch) ; 
Given a mouse location, such 
layer, this call returns Fa 


inder the mouse in clickedLayer. If th 


If the layer was not the frontmost and re- 


turn True in causedLay 


*n the Layer Server wilLat 
rontmost layer in ol 


If the layer under the ecome the focus for such 


events and the Lay 


use location accepts non-positional events, 
ver will return True in caused FocusSwite¢ 


“Boolean L 


Given a location, this returns t If there is 1 
call returns False. Unlike HandlePosition 


event focus. 


Boolean Nc ositionalEventLay 


Returns in the 
layer. 


Ositional events: Sno such 


Information Caching 


The client interface to the Layer Server caches some information locally, in order to avoid sending re- 
quests to the Layer Server. 


First, TSystemLayer, TLayerAlias, and TSurrogateLayer all maintain the owning task of the layer in the 
client object. If you create an object by supplying only the layer ID (not possible with TSystemLayer), 
then the client object records the fact that the task is unknown. The first time GetOwnerTask is called, the 
client object will send a request to the Layer Server to get the task. The cached task is also invalidated if 
you change the layer ID of the object. 


Second, TSystemLayer and TLayerAlias cache the layer’s visible region in the client object. Unlike the 
owner task, the visible region is modified by the Layer Server asynchronously from its client. When the 
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Layer Server changes a visible region, it updates a shared seed associated with the layer. The client 
objects examine the seed to determine if the cached region is still valid. If it isn’t then the object sends a 
request to the Layer Server to get the latest region. - 
Clients of the Layer Server can also test the visible region seed. This is useful when a change in the visi- 
ble regions requires some response from the client. For example, the View System recomputes each 
view’s visible region when the layer’s visible region changes. 


Finally, TSurrogateLayerServer caches the layer that currently handles keyboard events. Again, the Laver 


Server updates a shared seed when this layer changes, and TSurrogateLayerServer only sends a request 
to the Layer Server when the cache is out-of-date. 


Internal Opera 


<To be written. This wil tre of the Layer Server and 


* [don’t particulariyike? 
which the non-positiona 


s built int ; vay in 


« Ifthe Layer Server has to have the no 


layer i Ir- 
rently uses right? : : : 
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The Albert Graphics Architecture 


Albert is the combined 2D and 3D graphics system developed in conjunction with the Pink system 
architecture. Albert accommodates the complexity of the current Macintosh hardware environment and 
provides additional extensibility and flexibility. By nature Albert is object-oriented. It uses a floating 
point number system to provide precision, range, and accuracy. It is device and resolution independent. 
It surpasses most of the combined functionality of Color QuickDraw, PostScript™, and Renderman™. 


This section reviews the Albert architecture, beginning with Albert's numeric system and both the 2D 
and 3D coordinate systems, in particular showing how the two relate to one another. With that 
established, we list the geometries available in Albert, followed by the transformation matrix classes. 
We next provide a brief description of bundles, which are collections of graphical attributes, including 
paint, color, styles, and shading methods. The descriptions of geometries, transformations, and bundles 
set the stage for an introductory discussion of imaging with Albert, including a small example. 


Numbers 


“objects, for example 
always expressed by the 
“Or various reasons involving 
how ANSI C is specifi in i ‘ype extended, also known as 


Albert uses floating 
polygons, are constru: 


Other numeric for i i 1€ ou y for most output 
devices but doe ; $ gh precision to 
handle complex ig it accuracy. 
i d smpromise. 
iould have 


X axis lie to 
coordinate s 


Figure 1. The 2D coordinate system in Albert 
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In Color QuickDraw a rectangle drawn from the values (1,1,4,3) would enclose exactly six pixels, as 
shown in Figure 2. Since all the original Macintosh displays had pixel sizes measuring 1/72 of an inch 
square, the area enclosed would be that of a rectangle measuring 3/72” in width and 2/72” in height. 
Albert assumes that a value of 1.0 will measure a distance of 1/72”, but it does not assume that such a 
value will span exactly one pixel. In anticipation of new, higher resolution devices, Albert has been 
designed to be resolution independent. The Albert result for the same rectangle on a higher resolution 
screen (144 dpi) is shown in Figure 3. Note that although 144 dpi is convenient for this illustration, the 
resolution is not limited to multiples of 72. 


(0,0) & , es es (0.0,0. of DAE OMS OI O/B @ [8 GHD . 


® tie a ale oe 6 & he wes +X 


me a co) poe bd pee is 6 
S & FE oS oe: ae 


The choice of ontroversy. 
An alternate that was"stt ‘ ipti Or example 
PostScript™, where positive y ¢ ir rk 
types of imaging easier at the expens 
(0,0) to the upper left corner of the ¥ 
orientation so that most coordinates wi 
systems are, ultimately, conventions, ma 
most attractive.option. 


was the 


: > sordinates along the X 
axis lie to the right of the origin, positive coordinates along the Y axis lie above the origin, and 
positive coordinates along the Z axis lie towards the viewer. The coordinate system is illustrated in 
Figure 4. 


Figure 4. The Albert default 3D coordinate system. 
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The 3D coordinate system is at odds to the 2D coordinate system in two ways. First, positive values for 
Y lie above the origin, not below. Second, the origin is positioned by default in the center of windows, 
not in the upper left corner. Both differences reflect the preferences of most 3D developers. [In practice, 
the inconsistency between the orientations of the 2D and 3D coordinate systems has not caused any 
major problems. By contrast, a prototype which placed the 2D origin at the bottom left did cause major 
headaches. Comments on this inconsistency are welcome, now. As time goes on, changes will become 
harder to make, so write early, and often.] 


The Integration of 2D and 3D 


The best way to understand how Albert integrates 2D and 3D imaging involves an analogy to how a 
camera works. Consider Figure 5, below. We have created an interesting scene between to clipping 
planes, a near clipping plane and a far clipping plane. A camera works by gathering light rays and 
projecting them onto film behind the lens. Of course the image comes out upside down, but film is easy to 
turn over. For imaging 3D graphics the projection plane can be set in front of the camera to get an 
equivalent result. We metries onto this Plane, and that proje 

imaging result. In Figu b 
model, after which w 
you would expect, Al 
the 2D and 3D syste 


Near Clipping 
Plane 


Figure 5. How Albert integrates 2D and 3D imaging 
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Albert bases most of its geometric objects upon points. Every primitive can be constructed from points, 
and every primitive, other than the rectangle and the box, can be arbitrarily transformed to produce a 
valid geometric object of the same type. 


Albert provides four types of points. The simplest is the 2D point, called TGPoint. It consists of two 
GCoordinate values, one for the x position and one for the y position. The 3D point, called TGPoint3D, 
has a value for the z position as well. 3D points are not derived from 2D points. To do so would imply 
that the two are directly related. They are not. It is quite true that a 2D point can be generated from a 
3D point, but the process involves an explicit process of projection. Such projection requires additional 
information to be properly done. Specifically it requires a 3D matrix. It is not sufficient to simply 
assume that the z value can be set to some constant. This will, in general, give the wrong result. 


The remaining two ty 
point, called TGRPoin 
controlling curvature 
described in a separa 


component, called w. Albert provi 
called TGRPoint3D. Rational pot 
s and nurb surfaces. The. 


ational 2D 
t useful in 
these points will be 


Points can be mani 
can be used. For € 
rational points thes 
points. 


ted ina number of ways. "They can be used. 
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tically very much as numbers 
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Geometry 
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Figure 6. Geometric primitives inherited from Color QuickDraw 


Albert extends Color QuickDraw’s set of primitives by adding a curve primitive and a path primitive. 
Examples of these new primitives are shown in Figure 7. 
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Curves 
Figure 7. New geometric primitives provided by Albert 


Albert actually provides three flavors of curves, as shown in Figure 8. Quadratic Beziér splines are 
familiar to users of MacDraw II® (Claris), while cubic Beziér splines are familiar to_users of 
PostScript™ (Adobe). A nurb is a powerful specification for arbitrary curves of great complexity. The 
name derives from the acronym NURBS, which in turn stands for Non-Uniform Rational B-Spline. 


Cubics 


Figure 8. Curves provided by: 


Albert extends 
in Albert, as sh 


RRO OA ON OR ORI 


3D Lines 3B 


Mesh Surfaces Polynet 


Figure 9. New 3D geometric primitives provided by Albert 


Transformations 


The most interesting way to manipulate a point is to transform it. 2D points are transformed using a 3x3 
matrix, called TMatrix. Transformation involves a matrix multiplication, illustrated below in Figure 
10 for a simple translation by 3 in x and 4in y. The non-rational point, TGPoint, is assumed to have a 
third value of 1.0. The rational point, TGRPoint, uses its w value as the third value, and for some 
transformations will use the full 3x3 matrix, as illustrated gratuitously in Figure 11. 
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Figure 10. The transformation (translation) of a TGPoint. 
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3D points are transft TMatrix3D. In general, 
ill be used when you are 


ion into a window ona 2D 


stencil. The 
Pa starting 


geometric primitive. Such class 
transformation information. 


result is the 
t. The first 


However, if you had started with a TGPolygon in the form of a star, and wished to place a series of 
stars around the perimeter of a circle, it would be tedious to precalculate the points for each of the star 
polygons. The easiest approach would be to create a single polygonal star and move it around the circle 
by manipulating a TMatrix. In this sense the polygonal star serves as a stencil, and the stencil is 
manipulated by using a matrix transformation. 


Of the various 2D geometric primitives found in Albert, the rectangle, called TGRect behaves slightly 
differently. A rectangle is constructed from just two 2D points. The points are insufficient to specify any 
arbitrarily transformed rectangle. Instead the points define the top left and bottom right corners of a 
rectangle which lies orthogonal to the coordinate plane. If you wish to image a rotated rectangle you 
must use a transformation. As before, you can treat a rectangle as though it is a stencil. When a rotation 
is applied to the rectangle it behaves as though a stencil matching the orthogonal rectangle has been 
rotated to the new orientation before the rectangle is used (for example, drawn). This process is 
illustrated in Figure 12. 
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gure 12. A stencil and a rotated stencil use 


In the image abo 
also shown on th 
rectangle is im 
that the rectang! 
internal data is not changed. 
imaging result will also be ic 
meantime. 


‘ectangle is illustrated to drawing surface. The surface is 
5 the erotated before the 


avi tis approach is 


The justification for having a rectangle of 
elements require the imaging of untransfe 
interface this 
2 on, involve 
structure of 


But a rectangle is really just an accelerated polygon. To that end ‘t-provides a special way to 
construct a rectangular polygon which can, because it is a polygon, be manipulated in a general way. 
Note that some 3x3 transformations, for example perspective transformations, will cause a rectangle to 
lose its rectangularity. 


The box primitive, called TGBox3D, has properties exactly analogous to the rectangle primitive. 


Text, Glyphs, and GlyphRuns 


Albert supports text at the most primitive level, i.e., painting characters on the screen. With the 
ability to paint international text and symbols, the term “character” is inappropriate; what is 
normally described as a “character” may actually be made up of several distinctly separate pieces of 
area-enclosing geometry, called glyphs. For example, an accented character like ‘é’ could be made from 
two separate glyphs, one for the ‘e’ and one for the “” accent. 


More sophisticated textual functions, such as kerning, editing, composing characters from composite 
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glyphs, laying out words, lines, and paragraphs, etc., are performed at a higher level by clients of 
Albert. This is because line layout and editing functions are an especially broad, complex, interactive 
application of text, which is beyond the scope of Albert. Albert’s responsibility is to be able to display 
text in any font, size, orientation, and style, as quickly and as easily as possible. To accomplish this, 
Albert text is divided into two areas, font management and glyph display. ) 


Glyphs 


The typical Albert user is primarily concerned about displaying glyphs. Fortunately, displaying 
glyphs is entirely consistent with the display of other Albert primitives. A glyph is simply another 
type of area-enclosing geometry. Glyphs are defined in outline form; that is, the glyphs are defined in 
terms of the curves that form the shape boundaries. This is in contrast to a bitmap form, in which the 
glyph is chopped into rectangles that represent the pixels of a raster image. The outline form can be 
scaled or rotated accurately, while the bitmap form is only useful at a specific size on a specific 
resolution graphics device. 


¥ character has an origin for 2 along a horizontal 


g along a vertical path. 


itmap glyph 
Figure 13. A comparison of an outline glyph and a bitmap glyph 
Glyph Runs 


Since text is most commonly displayed as a string of characters, Albert’s basic text object is not a single 
glyph, but a collection of glyphs called a glyph run. The glyph run contains three types of information 
which completely determine the text’s geometry. The first bit of information is a font descriptor, 
which includes information such as type face, point size, and style. The second piece is an array of 
glyph codes which index into the font. The third type of information provides for positioning in the 
form of an origin and an orientation for each character in the string. Orientation is recorded as a text 
path. The most common paths, such as horizontal or vertical, are recognized and handled as optimized 
special. cases. However, Albert also allows you to place glyphs along arbitrary paths, where the 
arbitrary path is represented by the geometric primitive called TGPath. 
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Font Descriptors 


The font descriptor (the TFont class) is the Albert client’s connection to Pink’s font mechanism, it 
contains the font name, base point size, and style information so that, given a glyph code, Albert can 
compute the exact glyph to be displayed. 


Albert will support at least two font formats, namely bitmap fonts and TrueType (Bass) outline fonts. If 
a font is requested for which, on a particular raster device, a preferred bitmap form is available, Albert 
will substitute the bitmap form for the outline form. Albert will not attempt to modify a bitmap form 
into one of a different resolution or style. If the bitmap does not match the font descriptor precisely it 
will not be used. ‘ 


A similar problem may arise in the event that data is imported from another system and a font is 


requested which is not available. Albert will not perform automatic font substitution, but will check 
for font substitution information stored in user preference information. 


Bundles 


e, which is called a 
: Consider the process of 
‘vender hue, or framed ina 
perhaps thick. It might be 
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TGrafBundle, is us 
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ese effects can be achieved by 
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igure 14. 


used attributeis p: ‘Paint. Paints control how a graf 
several interesting paint, but certainly the most interesting ; called a TColor. In the 
process of trying to standardize colors the graphics industries seem to have created a huge quantity of 
color spaces. Each of these can be derived from TColor, and many of them are predefined by Albert. 
These will be listed later, in the chapter describing bundles. 


Some paints use more than one color. A pattern, for example, could include an arbitrary number of colors. 
Or a paint might be created which would use an image as a pattern. A ramp, from one color to another, 
is yet another interesting kind of paint. Transfer modes, including blending, also fall into the category 
of paint. But paints don’t even have to involve color at all. A paint could be designed to write bits into 
a mask plane on a device which supports live video. The effect of using such a paint would be to cause 
live video to appear whereever the paint was used. 


2D Attributes 


_ Some attributes are specific to 2D primitives. For example, there are a few 2D primitives which 
enclose area: rectangles, ellipses, round rectangles, polygons, glyphs, and areas. Each of these can be 
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either filled, or framed, or both, and which is done as a property of the GrafBundle. Several 
properties affect how all 2D objects are rendered. Line styles, endcap styles, and join styles can affect 
most 2D primitives. A line style object, called a TLineStyle, can be used to control dashing, whether 
the pen is centered, inset, or outset, and it specifies a pen width. An endcap style object, called a 
TEndCapStyle, can be used to control the form of endcaps on open-ended geometries such as lines and 
curves. A join style object, called a TJ oinStyle, can be used to control the form of joins on objects which 
have joins, such as rectangles, polygons, or polylines. 


3D Attributes 
With a sufficiently powerful 2D system it is possible to create images with many of the characteristics 
of 3D images. The problem is, it’s hard, not very intuitive, and if anything simple detail changes you 
may have a lot of work to do. The goal of most 3D imaging is to create a somewhat photorealistic 
picture of one or more interesting objects. The real power of this approach comes from modeling. If 
models can be turned into accurate pictures, then the problem has been reduced to one.of creating 
interesting models. In ter problem to solve. . 


ye no real parallels in 
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Figure 15. The class structures for TRect and TLine 
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Because graphic objects group geometry and graphic attributes, each one can be described as a small 
picture. But since each graphic object descends from MCollectible, they can themselves be placed in a 
collection, in this case a graphic collection called a TGroup. [ This section could not be finished prior to 
the publication deadline. Please refer to the next section, 2.3.3, which ts included in this release and 
which describes graphic objects in greater detail. ] 


Images 


The Image object, called TImage, contains a graphics device which serves as an offscreen frame buffer. 
It can be manipulated as an MGraphic. You can also create a port based upon a TImage and draw to it 
just as you might draw to the desktop. [ This section could not be finished prior to the publication 
deadline. Section 2.3.8, which describes Albert's handling of images in greater detail, will be 
forthcoming. ] 
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section, 2.3. 
Regions 


Regions provide a mechanism by which Albert and the View system can share a limited resource such 
as the desktop. Each ViewPort (GrafPort) built upon the desktop contains a Region which defines how 
much area it has reserved on the desktop GrafDevice. 


The TGrafRegion class is also an abstract class. GrafRegions can be added, subtracted, intersected, or 
exclusively complemented (exclusive or’ed, but how the heck do you say that in English?). GrafRegions 
are created by GrafDevices, because only GrafDevices know which sort of GrafRegion will be 
appropriate. For example, the TFrameBuffer GrafDevice creates a GrafRegion of type 
TRegionFrameBuffer. 
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Architectural Principles | 


In the process of creating Albert, we spoke with a great many graphics experts at Apple, most of whom 
are acknowledged on our cover page. From these discussions we developed a series of Albert Principles. 
These are not offered as being original to Albert, but rather are included here because they are 
fundamental to the Albert architecture. 


The Principle of Simplification 


To quote Alan Kay, “simple things should be simple. Complex things should be possible.” The goal is 
to have a simple process, such as drawing a line, to be a trivial process. You don’t have to initialize 
anything, or start up the graphics system. Just get a GrafPort and draw a line. 


ne.Draw(Port); 


Ort reason 
Pink system a Poniieéture: and 

to follow in kind. That doesn't mea st 
with the rest of the Pink architecture. 


The Principle of Inversion 


nemselves. Consider the (non- Al > 


YourApplication::Main() 


TRectangle Rectangle ( 40, 40 ); 


Rectangle.Move ( 30, 30 ); 


Rectangle.Draw (); 


Figure 16. A common object-oriented programming example. 


While this approach makes for a nice example, it is clear that the authors haven't actually tried to do 
much with it. They certainly didn't try to accommodate a hardware platform as robust as the current 
Macintosh. The problem can be stated simply: how does the rectangle from Figure 16 understand how to 
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draw itself in an environment far more complex than the one for which it was originally designed? The 
authors have presumed a static environment, where the process of drawing a rectangie never varies. 
This can be easily thwarted in the Macintosh environment by simply adding another monitor to the 
desktop. Of course, the rectangle object could be designed to understand multiple monitors. But then 
what about graphics accelerators, or video, or the neat new graphics hardware announced tomorrow? - 


It becomes clear that the most interesting object in the Macintosh hardware model is the graphics 
device, not the geometries. Regardless of what type of hardware it is, a graphics device isn't 
interesting unless it can draw geometries such as the rectangle. Exactly how that occurs is important to 
the graphics device, but not to the rectangle. Therefore the foundation of imaging in Albert looks, 
although not exactly, like the example code shown in Figure 17. - 


YourApplication::Main() 


Having solved 
interface simila Lé&by i i ss ef Figure 17. This 
inversion is ap j hic : 

device through: 
which requires a parame 
of a graphics port. The graphics 


_ the form 
nal result, 


Jraw (Port); 


TRect::Draw ( TGrafPort* Port ) 


Port->Draw ( this ); 


TGrafPort::Draw ( const TGRect& Rectangle ) 


fDevice->Render ( Rectangle, fGrafState ); 


Figure 18. The three imaging layers of Albert 
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In Figure 18, the imaging call denoted by "Rectangle.Draw(Port)" is the preferred imaging layer. As 
will be described: later, the TRect object actually includes more than just geometry, so the model 
portrayed above is somewhat simplified from the real model. In fact, the geometry portion of TRect is 
a separate base class called TGRect. However, the figure serves to illustrate the inversion from a TRect 
which knows how to draw itself (given a TGrafPort "where" parameter) to a TGrafPort which knows 
how to draw a TGRect. The TGrafPort adds certain pieces of information to the imaging process (for 
example, window positioning) and passes the call to the graphics device upon which it was built, a 
field {Device of type TGrafDevice. 


The Principle of Justification 


All of which leads to the principle of justification. In the examples above an extra imaging layer snuck 
into the discussion, nay tat of the oO The principle of justification demands that each 
layer in the hierarchy provi REE _ s 


The top imaging layer objects, provides polym 


plications. Graphic obj 


extensibility. It 
layer all descend from 


bea is derived froma simpler base cl 
as TGRect. 
There are many 
TGPolyNet3D 
more than one 
shaped polygon called“ FBi 

shapes, such as TSphere, TConé 
TGSweep. 


The grafport layer lies in the middle. 
locality. This is done by collecting certain 3 
clipping, int f is thi ehicle for 
interaction b : at i ; 
grafport, c “system can 
function corr / 
The grafdevice yer ‘lie uld not make calls 
directly toa erafdevice: But then, you should not be making calls directly to a grafport, either. The 
grafdevice layer provides Albert's contract with both internal and external developers of graphics 
devices. The graphics device developer need implement a fixed number of imaging calls in order to 
accommodate the full range of Albert's graphics capabilities. 


The Principle of Localization 


Which leads us to the Principle of Localization. The key to imaging with Albert is that at the time of 
an imaging call to a grafdevice, such as the Render (Rectangle, fGrafState) call in Figure 18, all 
information relating to the imaging process has been localized in the parameters to the call, the 
geometry in Rectangle and everything else (color, style, shading, transformation, and clipping) in 
fGrafState. 
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Perhaps one of the most important lessons we learned from QuickDraw (actually, from our esteemed 
colleagues who made QuickDraw print) is that it is important to gather all of the information used in 
the imaging process into one place at the time of the imaging call. In QuickDraw the classic problem is 
one of developers making modifications to the data structures of a grafport without using access 
methods. The change in state thus does not get recorded in a manner that the graphics system can 
accommodate it. 


In Albert , the problem of hidden change is defeated in two ways. First, there is no equivalent to 
QuickDraw's SetPort(grafPort) call. All imaging references a specific grafport. In fact, Albert 
maintains no global state whatsoever. There is still room for developers to get into trouble. They could, 
for example, discover ways to change fields in Albert's various graphical attribute objects without 
using access methods. Albert solves this problem by ignoring such changes. 


Principle of Abstraction 


h; ted another 
“Behind the curtain." 
«Draw provided regions, 
certain kinds of extensions 


Closely related to the 
way, means "you da 


the Principle of Abstraction; 
or "pay no attention t 
Perhaps the best ex ss, called TGrafRegiot 
and quite useful beasts: they: were. QuickDraw:also patented regio 
a notoriously tricky thing to do for the Macintosh platform. 


tion based substantially on the 
assumptions about regions in the 
tos ect windowing and 


egions, and we have our own 


course of using 
imaging results, 
need to undefs 
guarantee that the implemen 


Of course, to accommodate our own gra 
class. For that matter, the TGrafDevic 
While we also need to instantiate sev 
> need not understan 


The advantage s that external developers can 
created a piece of hatdware which is not a frame buffer, an pon which running 
TFrameBuffer code would be inappropriate, they can create. their own grafdevice which satisfies the 
TGrafDevice interface, say TWhizzyGrafDevice, and all will be well with Albert. Of course, it is 
likely then that TRegionFrameBuffer will also be inappropriate, so they'll probably need a 
TRegionWhizzyGrafDevice as well. 


Principle of Declaration 


So, in principle, it's better not to know what's going on behind the curtain. Which creates a bit of a 
_ problem, because traditionally Macintosh developers like to peek in on what's going on back there. The 
trouble is, it won't always be possible to look. If your application is trying to be clever and check up on 
all grafdevices in the world and do the best thing for each one, you are guaranteed to encounter a 
situation you haven't anticipated, meaning TWhizzyGrafDevice which was announced a couple of 
days after your application went final. At best, your application won't draw properly. At worst, it 
will crash or fail in some way. 
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The solution to this dilemma is to rearrange your thinking on what you're trying to do. In general, you 
have a particular goal in mind, and the motivation for peeking behind the curtain comes from wanting 
to do the right thing in each particular case. The problem can be turned around, though. Suppose you 
state, in some predefined way, what your goal is. For example, you wish to draw a rectangle which has 
lines inset from the actual perimeter of the geometry and which all appear to be the same thickness. 
The temptation is to check up on the device resolution, anticipate out how rounding will occur, and 
specify the appropriate line thickness for each part of the rectangle in order to get the appropriate 
result. Unfortunately, it turns out that TWhizzyGrafDevice is a graphics accelerator of unknown 
composition, and it doesn't make its resolution available, perhaps because the concept of resolution has 
no meaning to the device. : 
What you really want to be able to do is to declare your goal for a particular imaging call, and allow 
the device to achieve your result by whatever means it has available. Albert supports this 
methodology by providing a flexible and extensible set of graphical attributes. However, 
determination of the initial set of available declarations is also one of the most challenging problems 
we face. 


Principle of Op 


In the early stages: 
the decision tree 
a great many dec 
decided earlier iz 


project (now called Skia) Cary G 
-Olor QuickDraw. Along the path of dra 
ns Many of these decisions were found 
g, but due to converg: 


uce Leak created a map of 
» object such as a rectangle lay 
essary; they had already been 
the information learned along 


the way had beg 
The Principle ¢ ag :f approaches 
are available ¥: \ le object to 


get to the rendering process a 


Take for example the problem found i monitors. 
After discovering that an imaging call t 
grafDevice and select the set of imag i Pp i Ibert, the 


Or, for exam : raf 
two or more GrafDevices.. a window is built upon such’ ster, its GrafPort contains a 
GrafRegion which reserves space on each device as necessary. If, as is likely to be the case, the window 
occupies space on only one device, the GrafRegion will understand and remember this information. 
When an imaging call occurs, the GrafCluster first makes a trivial check to see if there is any 
possibility of drawing to a device by asking the GrafRegion if any space has been reserved. If not, the 
imaging call is never made to that device. 


One trick we use to make decisions only once involves arranging the decision tree such that decisions are 
made at the proper time. In general, the proper time is determined by minimizing calculations for the 
most frequent imaging calls. For the Macintosh system these calls involve simple geometry, including 
text, rectangles, lines, and copied images (although not necessarily in that order). The most common 
graphical attribute is color, in particular solid colors, especially black and white. The most common 
transformation is a simple translation, such as the screen offset of a window. The most common clipping 
is unclipped. The decision tree is established with these frequencies in mind. The most frequent cases 
are checked first. 
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Consider our implementation of the frame buffer GrafDevice. If a rectangle is being imaged, the 
GrafRegion of the GrafPort in use is asked whether the rectangle is clipped. If not, the flow of control 
passes to a routine which optimizes the unclippped case. No further consideration is made for clipping 
along that path. If the rectangle is being clipped, a different path is taken which reads the 
GrafRegion structure to produce the correctly clipped result. The clipping descision is made exactly 
once, and is made by the entity which understands clipping, namely the GrafRegion. 


Principle of Acceleration 


Another way to achieve optimal result is by using accelerated forms. For example, a rectangle could be 
expressed as a polygon, and could be imaged correctly in all cases. Rectangles, however, are imaged 
frequently, and can be handled in simpler, faster ways than general polygons will allow. Recognizing 
this, we offer rectangles as a separate primitive in Albert. 


We handle curves in a slightly di ay. Albert offers three flavors of curves, namely quadratic 


Bézier splines, cubic Bézi¢ 


srafDevice recognizes 
y, resulting in optimal 
aving a separate class for 
ng each type in a slightly 


curves, there is no adv 
eal of advantage (at the frame buffer leyel 


performance for eac] 
each type, but a gre; 
different way. 


A third exampl In common use, most 
transformations: | sg ombination of 
translation and $ s desi Pe) D Consider the 
operation of tr 3 
returns the point unch 
matrix multiplies each componen 
component. Only complex (non-affi 
such matrices are used infrequently. 


anpe ix simpl ‘ . A scaling 
son § . to each 
tion, and 


Principle of Procrastination 
Another pri t off until 
tomorrow w 
opposed to 


having never done the complicated intersection calculation. 


Principle of Perfection 
We can do better than that, though. If in fact we never perform the intersection we can produce a more 


accurate result. Take for example two interesting shapes, a complex curve resembling a flower and one 
composed of concentric rings. 
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Figure 19. Addition of two TGArea objects to create a more complex form. 
The addition of these two objects creates an interesting geometric form, but calculating the precise 
geometric form can be expensive and tricky. However, rendering each form independently is a well 
characterized process. If we delay the intersection process until rendering time, we can deal with a 
much simpler problem. In the case of a frame buffer we can deal with discrete pixels. In the example 
above, a pixel will fall..in.one..of.the.two.areas,.and be drawn, or not. We never have.to:calculate the 
precise intersection of der to render the addition re 


ven with high-precisi 
calculations which 
ag’ d separately, and overlaid, versus im 


At the same time, 
introduce numerica 
each object being i 


e point it is possible to 
id to a different result for 
ded result from the Area. 
2 of the “perfect” result. 


font the user da F si Econsultation 
with the user. Such constiltat 
direct Albert towards a differerit 


the right size. 


font into 


Principle of Precision 


‘was useful 
it failed to 
Second, it was 
ter all, a span. of 
tions the coordinate 


E ough to span the entire 
e size pages at 72 dpi. At typica 
plane is exhausted after 0 y 1 pages. 


Two 32-bit solutions were considered, namely fixed point integer (16.16) and single precision floating 
point. The first has improved resolution with sub-pixel accuracy but has no more range than Color 
QuickDraw. The second offers much improved range, but precision varies significantly depending upon 
which part of the coordinate plane is used. 


After much pontification of this problem our favorite numerics expert recommended 64-bit double 
precision. Although a tad bit on the heavy side at 8 bytes, double provides the best balance among 


precision, range, and size. It also allows us to provide rendering of higher order primitives such as nurbs 
and nurb surfaces and to create well-behaved matrix classes. 


Principle of Indiscretion 


In this case, indiscretion means non-discrete. The Principle of Indiscretion means simply “use higher 
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order descriptions of geometry whenever possible," A quadratic Beziér spline, for example, can be 
described in a number of ways. A series of short, connected line segments which follow the curve can give 
excellent results on some graphics devices. However, if the resolution of the graphics device is greatly 
increased, it will at some point exceed the resolution used to select the line segments themselves. At 
such a point the intersections of the line segments will become visible, as illustrated in Figure 20 


A better approach is to represent the quadratic Beziér spline as three control points. Even if the 
rendering technique involves the creation of short line segments, if the process of creating the line 
segments can be delayed until the resolution of the device is known, we can be assured that the 
resolution used to create the line segments will be sufficient to produce the correct imaging result. 


This approach is even more important to 3D imaging. The analogous problem involves the 
representation of 3D surfaces. The less preferable solution involves using a series of small, connected 3D 
polygons to describe them. At high resolutions the edges of the polygons appear. Consequently, a 

number of polygon shading techniques have been devised in order to smooth away the edges and make 
the surfaces appear p 


Figure 20. Using line : 


However, consider the problem of using 
sculpting machin The smoothing tec 


appropriate, but oth 
prohibited. T y might use the control point 
across the surface to produce the desired result. 


Principle of Integration 


Albert was designed to integrate the 3D system with the 2D system. It isn't always possible to 
maintain consistency between the two worlds because imaging in each is fundamentally unique. For 
example, the most popular choices for orientation of coordinate systems in the two worlds do not match. 
Points and transformations, while somewhat related, are used in different ways in 3D as compared to 
2D. And, perhaps most importantly, the goals for each kind of imaging are quite dissimilar. 


But there are a great many things we can do to integrate the two environments. First and foremost, you 

don't have to make any special calls to start up the 3D system. It's there and ready to go as soon as you 

get a GrafPort for drawing, just like the 2D system. Because each system uses the same numerics, 

conversions between 2D and 3D data structures can be done ina straightforward manner. Objects, such as 

_ colors, are shared between the two worlds. Naming conventions, and the kinds of calls made to image 
each type of object, are consistent. 
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Principle of Organization 


The Principle of Organization states that "display lists are a bad idea. There shall be no display lists 
in Albert." Well, maybe one or two. The basic problem with display lists, especially those at the 
device level, is that writers of most interesting applications will want to organize graphical data 
according to the particular needs of the problem being addressed. If the system maintains its own 
display list it pretty much guarantees that two copies of the data will be maintained at the same time. 
Silicon Graphics went down this road for awhile, then turned around and came back when it proved 
untenable. 


However, the preferred imaging layer of Albert sure looks a lot like a display list. It is hierarchical, 
has groups and instances, and can be imaged witha single call. But here's a secret, just between you and 
Albert. Don't tell anyone else. The top layer of Albert is optional. The top layer of Albert is called 
the MGraphic laye! ts each descend from that (mixi 
completely upon the: 
used to build an al 


MGraphic layer ; he MGraphic layer for all of 
your imaging neex 


you. Albert 
© long as you 


The same is true for most Albert s i ‘ within the 
parameters of what a GrafDevice exp or spaces, 
you can add new line styles, new end caps : S 
Principle 

Of course, ant orks. be i a rr ‘ Omething. Take 
frame buf want to saplementy y e ions. The path 


and area primitives ert allow you to extend their geometrie da tures in arbitrary ways, 
provided you can relate the data in some way to the standard structures. In the event that your 
structure is imaged to a standard GrafDevice, the conventional information will be used. But, if your 
structure is imaged on your special, extended GrafDevice, you'll get whatever result you had in mind. 


You don't have to implement an entire frame buffer to make. this work. You simply have to derive a 
frame buffer from one of ours. In the render method for paths and areas you will first check the data 
structure to see if it is yours. If not, pass it up to the parent render method for processing. But if it is your 
special structure, you can image it in your own special way, or perhaps do a bit of processing and use 
standard calls to do the imaging. You get a new type of frame buffer for the cost of implementing part of 
a single routine. 
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Imaging With Graphic Objects taescrived by Roger Spreen] 


As described under the Principle of Inversion, Albert supports the concept of a graphic object layer so 
that you can declare and render graphics in an intuitive, object-oriented fashion, irrespective of the 
device-centered layers underneath. This concept assures that your task of actually putting graphics on 
the screen is as simple as possible: usability is of prime importance. 


It is important to understand that you can use any of the different “layers” of Albert and still achieve 
exactly the same results on your graphic device. These “layers” are simply sets of classes and methods 
which provide you with a slightly different paradigm for managing your graphics. For most standard 
graphics applications, the Graphic Object layer will maximize your convenience and minimize your 
development time in building an application. 


The Components of a Graphic Object 


No matter how you sli Mayer” you use, there is still 
information you mu etely specify a graphic effe 
chooses to divide thi arate components: 


¢ Geometry: gi shape, e.g. lines 0 


P 


e Transforms ‘bitrary matrix transformations, most 0 


fioneratation, and scaling. 


e Bundles: 


This division of inforn ; i either in 
hardware or software, wi em. The 
Graphic Object layer organizes the 3 s, where, 
in general, each class represents a diffe : 


Transforms 


Graphic Object 


Figure 1. Components of a Graphic Object class 
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Advantages of the Graphic Objects | 


Primarily, the Graphic Objects offer you convenience. Albert can leverage object-oriented programming 
to encapsulate the three components together, eliminating the need for you to manage all the pieces 
yourself. Furthermore, just by forming a simple collection of Graphic Objects, you can have “Display 
List” functionality which is still device-independent. (For convenience, the Graphic Object class 
includes two built-in collections: a simple grouping object and a hierarchical grouping object.) Thus, a 
collection of Graphic Objects can serve a similar purpose as QuickDraw’s “Picture.” Similarly, the 
Graphic Objects can also be used to transport graphics from one application to another. One additional 
advantage of using a collection of Graphic Objects as a clipboard medium is that it can easily be edited. 
The generic nature of the objects in this layer means that you can write routines that handle Graphic 
Objects without knowing their internal details. Existing applications that handle Graphic Objects 
generically (such as in a display list, or from the clipboard) will automatically be able to handle new, 
custom Graphic Objects that are placed in the system. 
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with Albert's 2D ca 


D and 3D objects. Thus, existi 
sas any other clipboard ob 
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MCollectibl 


MGraphic :: Method1() 
MGraphic :: Method2() 


An appropriate Geometric Class 


Custom Behavior (optional) ——3> | Graphic Object :: CustomMethod10) 
Graphic Object :: CustomMethod2() 


Geometric Behavior (optional) —> 


Figure 2. Graphic Object class structure 
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The complete set of Graphic Object classes is listed below (along with the geometric class it is derived 
from, if any). Note that there is no Graphic Object point, since Albert does not render “points” per se; 
depending on the resolution and characteristics of the output device, a “point” could be of arbitrary size 
and shape. Is a “point” square, rectangular, oval, or round? Thus, to render what we think of as a 
“point” or “marker,” it is necessary to render some specific geometric shape at a specific, device- 
independent size. However, it is obvious that “points” are a useful concept in a graphics system, so 
throughout Albert, and more specifically, throughout the Graphic Object classes, the Geometric class 
TGPoint is used for specifying coordinate data. 


Line-oriented 2D classes 


¢ TLine: _ Aline segment formed by 2 endpoints (TGLine). 
¢ TAre: An arc defined by 3 points (TGArc). 
¢ TCurve: A general purpose approximating spline curve; depending on the number of 


control points given, this can be a Quadratic Bézier curve, Cubic Bézier 
re (TGCurve). 

‘segments (TGPolyLine). 

of connected 2D line-orien: 


¢ TPolyLine: 


e TPath: ries (TGPath). 


Your classic rectangle, defined b 
pone (TGRect). 


‘left and lower-right corner 


¢ TLine3D: 
° meas age 


ight rectangular prism (TGBox3D). : : 

e TPolygon3D: A polygon with an arbitrary number of 3D vertices. (TGPolyN et3D). 

¢TPolyMesh3D: A set of connected, 4-sided polygons formed by 3D vertices that 
topologically form an array, thus yielding a “patchwork quilt” of polygons 


(TGPolyMesh3D). 

¢ TPolyNet3D: A set of connected polygons formed by an arbitrary number of 3D vertices 
(TGPolyNet3D). 

¢ TSurface3D: An approximating-spline surface formed by a mesh of 3D control vertices 
(TGSurface3D). 

Image classes 

¢ TImage: A 2-dimensional array of pixel values, a.k.a. “Pixmap” (no geometric 
equivalent). 
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Graphic Collection Classes 


¢ TGroup: A simple list of other Graphic Object objects. 
¢ TInstance: A reference to a single Graphic Object object, along with a unique 
transformation matrix. 


Graphic Object Methods 


By virtue of descending from the MCollectible and MPersistent classes, a Graphic Object can be used 
with the various collection classes, and it can be “streamed” to provide a basic storage, retrieval, and 
communication mechanism. By virtue of being a descendant of MGraphic, a Graphic Object gains 4 
additional capabilities: Rendering, Transformations, Bundles, and Hit Detection. 


ject, whether 2D or 3D, is “Draw( T )”; thus, you 
simply tell the object where to draw itself. All the remaining information need by Albert is contained 
within the Graphic Object. 


ise 


ES SOS 


TGrafPort portl, port2; 


object .Draw( &portl ); 


TGraphic object | CPbject.Draw( &port2 ); 


SE 


Figure 4. Rendering a Graphic Object 
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Since a Graphic Object and a GrafPort both contain transformations and bundles, it is important to 
understand the interactions between the two during the “Draw ()” process: the Graphic Object sends its 
geometry into the GrafPort to be rendered there. If the Graphic Object has a bundle, it sends that into 
the GrafPort, and its values take precedence over those of the GrafPort’s bundle. The GrafPort’s bundle 
is used only to provide defaults for values that the object’s bundle does not specify. Thus, if you leave 
values unspecified in an object’s bundle, you are relying on whomever sets up the GrafPort’s bundle 
values to “do the right thing.” The Graphic Object’s geometry is additionally transformed by the 
GrafPort’s transform (via post-concatenation). This makes it simple to transform all objects in a 
GrafPort, so that a GrafPort can, for example, translate everything rendered inside itself to achieve a 
scrolling effect, or for another example, scale everything to achieve a zoom-in effect. 3 


This generic “Draw” ability makes it simple to handle all Graphic Objects generically. For example, 
an application can simply keep a list of all such objects, and can render them all with a simple loop: 


c* objects{], int cnt, 


i void Render 
: TGrafPo1 


“‘OO0666606 


_Figure 5. Rendering a di 
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MGraphic::Translate3D( const TGPoint3D& ); 
i MGraphic::Scale3D( const TGPoint3Dé& scale ); 
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Figure 6. Transformation methods 


A TMatrix represents only a 3x3 transformation matrix, which is insufficient for 3D graphics. Thus, the 
TMatrix3D supports a full 4x4 transformation. There is no danger in calling “Transform()” ona3D 
object, or “Transform3D()” ona 2D object; matrix elements will be discarded or added as necessary. 
For details on creating transformation matrices, see the appropriate chapter. 


Since most transformations tend to perform translation and scaling, the MGraphic class supports these 


methods explicitly, which saves the trouble of having to work with matrices. With “Scale (),” the 
first TGPoint gives the X and Y scaling, and the 2nd TGPoint indicates the point about which the 
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scaling should occur. Just as with the “Transform()” method, there exist equivalent 3D forms of 
Translate and Scale (and again, it is safe to mix these calls with 2D graphics or vice-versa): 


Bundles 


Because a bundle is simply placed inside it, the MGraphic class only needs to provide “Get” and “Set” 
methods. For details on creating and modifying bundles, see the appropriate chapter. 


void MGraphic::SetBundle( TBundle* ); 


TObjectBundle* MGraphic::GetBundle(); 


Figure 7. Bundle methods 
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Boolean MGraphic 


i Boolean 


MGraphic: 


that are on the curve.“ f the Graphic 
App opriate in this calculation. (For: étBounds () returns 
the bounding rectangle that represents only the Z-axis projection; i Lé., it ous the (X,Y,Z) bounds and 
then eliminates the Z value.). “Get Bounds3D()” returns the smallest 3D Box (aligned along the 
coordinate axes) that completely encloses the object. 


“Intersects ()” indicates whether the given rectangle intersects any point on the Graphic Object. 
(For area-enclosing Graphic Objects, this includes any point inside the area.) 


“Contains ()” indicates whether the given rectangle is completely contained by the Graphic Object. 
(Note that “Contains” has not yet been implemented for line-oriented Graphic Objects.) 
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Text at the Albert level means simply the painting of characters on the screen, with no editing or fancy 
layout facilities. Actually, with the ability to paint International text and symbols, the term 


“character” is inappropriate. What is normally thought of as a “character” may actually be made up 
of several distinctly separate pieces of area-enclosing geometry, called glyphs. 


Text: the TGlyphR 


For the purpose of rendering text, Albert treats glyphs as any other piece of area-enclosing geometry. 
Since text is most commonly displayed as a string of glyphs, Albert supports a collection of these glyphs 
in a “run of glyphs,” or “glyph run.” The geometric class is TGGlyphRun, and following the normal 
Albert naming convention, the Graphic Object class is a TGlyphRun. As with any Graphic Object, it has 
a Bundle that determines its colors, etc., and it is rendered simply with “Draw ().” For more details on 
this class and on Font Management, see the appropriate chapter. 


I th a IS a ee 
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The TGroup Collection 


Albert supports two commonly-used types of “display list” collections; by making these collections 
Graphic Objects themselves, they can be rendered, hit-tested, or transformed in exactly the same ways 
as described above. 


The TGroup class is a simple array-style list of graphic objects. It offers methods for inserting and 


removing items from the list, much like the functionality of the underlying Pink Toolbox TDeque 
classes. The more complex methods use a TGrouplterator facility. 


i // Adding to the list 


i void Add( MGraphic* newObject ); 


i void AddFirst( MGraphic* newObject ); 
i void AddLast ( MGraphic* newObject ); 


MGraphic 


phic* obj ); 


MOVER: 
RemoveFirst(); // returns the. 
RemoveLast(); // returns th item 


0600606666606666666666666060566 


MGraphic* 


Figure 


itself a Graphic Obje ¢an contain ; erarchical 


Simple TGroup 


Rendered Result: 
TGroup.Draw( port 


Hierarchical TGroup 


Figure 12. Using TGroups to make a hierarchical display list 
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TGroup Methods 


In general, a TGroup method recursively calls the same method of all the children. Thus, if one TGroup 
contains another, the hierarchy will be traversed in a depth-first search manner. : 


* Get Bounds: recursively gets the bounding box of all control points 
from its children, and returns the bounding box that 
encloses all the children’s bounds. 

*Intersects: | recursively calls Intersect for each child, and returns 
TRUE as soon as any child reports TRUE. 


e Contains: gets the bounding box of the TGroup (see Get Bounds), 
and returns TRUE if the given rectangle. tained. 


* Scale, Tr recursively calls the appr. éthod of each 


§$ Draw method.. 


dle operations to modify it. It 
Be especially when used with 
rovide défault values where the 


is important to : 
hierarchical grou] 
children’s bun 


previously, the GrafPort uses its pundl 
the children, it restores the GrafPort’s't 
changes the GrafPort’s bundle, all the ot 


Note that 
could be af. 


render that child repeatedly, as many times as it appears in the list. ortuna ely, that child will be 
rendered repeatedly at the same location, on top of itself, over and over; after all, there’s nothing that 
distinguishes one reference to that child from another. 


Thus, an additional class is offered that can distinguish the multiple references: the TInstance class. A 
TInstance is a collection class that holds only one child, but also includes a transformation matrix 
(TMatrix) that is applied to the child when rendering it. This is performed by: 


1. Pushing the GrafPort’s internal matrix stack to save the current matrix. 
2. Pre-concatenating the TInstance’s matrix onto the GrafPort’s matrix. 

3. Rendering the child (which may be a TGroup or another TInstance!). 

4. Popping the GrafPort’s matrix stack to restore the previous matrix. 


Notice that by using the matrix stack, it allows recursive rendering of TGroups and TInstances. You only 
_ need to worry about the appropriate transform in the specific TInstance, and the rendering process of 


Draw() will manage the recursion. 


a a 
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TGroup 


Tinstancel TInstance2 TInstance3 


f Translate 3 Translate, 
Scale 


Translate, 
Rotate 


TImage 


With new devices like scani 
growing emphasis on “Multi-medi 
Macintosh feature. However, the c 
images is very clumsy, leading to f 
Applications tend to be tightly tied to 
specific resolution 


ampling parameters. Albé c 
that an Image can: be ad'on any device in the system in a mann ransparent to you.. By 
default, you need not worry about the resolution or color palette of a specific device; Albert simply 
displays the image at the highest quality the device can achieve, using whatever color matching 
techniques are necessary. Shrinking, stretching, rotation, warping, etc., are all functions which Albert 
will also support in order to make image processing more accessible to developers. 


Albert supports images with the TImage class, which is just another Graphic Object. Thus, images can 
be rendered with the standard “Draw()” method. However, because of the potential complexity of an 
image, there are a number of additional parameters and concepts required to set up a TImage; for more 
details, see the appropriate chapter. 
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The Outer Limits 


Printing Architecture Overview 


“There is not 
printer. We are controling: t 
vertical. We can clip the’outp a 
or sharpen it to crystal clarity. “Fo 
see and hear. We repeat: There is not 


to experience the awe and mystery whi 
PLEASE STAND BY...” 


. Bayles Holt | 
Ryoji Watanabe 
Jay Patel 
Mahi deSilva 
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I. Introduction 


This document gives a brief overview of the printing architecture. Printing,.as far as this 
architecture is concerned, also includes scanning, plus other forms of multi-media, specifically 
video, cameras, frame grabbers, film recorders, plotters, and VCRs. In addition, because 
animation is a major component of the Pink environment, the Printing architecture provides 
some facilities for printing frames in an animated sequence and for synchronizing sound with 
the animation. The printing architecture is viewed as a low level platform for video, multi- 
media and animation uses. 


The architecture is designed to be simple and easy for novice users, but also flexible and 
extensible enough to provide facilities for the most sophisticated application. 


All imaging within the Pink 
and imaging system 
the resolution of any, 
initially intended for 
gratuitous reforma 


device-independent, that is, the graphic model 
lution, and no assumptions are ms 
this really means is that any pri 
‘directed to another target.w 


the document. 


wis 


of which is Jaguar. 


Goals 


The major goals regarding printing in the new system are to produce a printing model that 
surpasses the capabilities found in any other environment including the original Macintosh. 
Known restrictions, that have plagued other models, have been removed and replaced with a 
more flexible model that allows expansion and growth, and adds additional facilities that 
make development easier, faster, and more secure, while at the same time providing 
consistency, device independence, and ease of use. 


In summary, some of the services provided by the Printing and Imaging architecture are: 


¢ Inclusion of multi-media and scanning facilities in the basic architecture. 


1 Objects such asTImages may have a specified sampling resolution, but this is a different 
animal. There is no overall implicit resolution in the graphic model. 
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¢ Support for other non-standard devices such as plotters, video recorders, and milling 
machines. 

¢ Automatic, high quality, device specific, ‘WYSIWYG’, including color matching. 

¢ User and application parameterization of all printing and imaging functions. 

¢« Automatic, overloadable device control for each printer, such as page ordering, bin 

selection, and so forth. 

Variable page sizes within a single document and support for custom paper sizes. 

Arbitrary page ranges with automatic collation. 

Automatic (client modifiable) printer specific optimizations. 

User alterable queues for background printing and remote spooling for all devices. 

Access to accounting and use-tracking as might be needed in specific printer 

installations. 

¢ Provide sub-document page reordering, collation, and job redirection, both before and 
after a job has been spooled. 


eoee¢ @ 


The rest of this document. will provide.a-basic. overview of an Imaging and Printing architecture: 
and present the clas tecture. We will describe how the 


classes operate and give some examples as to 
used. 


Il. Archite ure and Overview 


‘ ae 
¢ Provide page set up. an 
e =6Print 

¢ Manage print jobs 


application 
interface < 


‘Suit its own nen re needs:: 


Color 


At the core of the printing architecture is the graphics model and at the core of the graphics 
model is the color model. The graphics model is documented heavily elsewhere but we will say 
a few words about color here. 
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While true perceptual color fidelity may not be truly achieveable without full environmental 
control, the imaging architecture does attempt to provide some degree of color consistency 
through color matching between devices. The color model is ultimately based on a central CIE 
coordinate color space, internal to the system, into which all devices may be mapped. Each 
device connected to the system is characterized by its color gamut and a transformation map 
that specifies the range of color available on the device. Any color data being passed between 
a device and the system is mapped from one to the other through this transformation. In this 
manner, any two devices can be color matched by at most two transformations, one to get from 
one device to the system color space and the other to get from the system color space to the 
second device. 


A number of alternative color spaces are also supported such as the well known RGB, HSV, 
HLS, CMY, Luv, and so forth. Some of these spaces, without a formal color specification (like 
RGB) simply use the intuitive approach. There are also a standard set of transformations 
available to provide conversion from one color space to another. 


> following diagram. Questions regarding gi 
can be parameterized and dictated by clier 


Figure 2. An example of the color model used by the printing and scanning 
architecture. 


Now that we have examined the color model, lets look at two other major components of the 
printing and imaging architecture, scanning and printing. We will present a brief summary of 
scanning, but the primary focus of the rest of this document will be printing. 
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Scanning? 


Scanning is defined as the process of inserting information into a document from some source 
external to the processor that is not generated directly by the user. Input data can be in the form 
of images, characters, video, Albert Graphics or any collection of these. 


Scanning Model 


Conceptually, scanning is simply the process of adding content obtained from an external scanner 
toa document. The data.of interest may optionally be saved in secondary storage for later use 

as well. Scanned information may be processed or filtered before it is placed in a document if 
desired. The filtering and processing step may be augmented by the application, by third 
parties or the user herself. 


fete etctetatetetete tate late eel canal etbeteten se teMpatetetets 


The types of preproces: 
recognition, feature § 
which allows the coli 


e image processing , compressio 


: toning or dithering als¢ 
and are not recommended for input scanning 


printing system < roduce much better 
quality if it is | : ms and other visual 
effects may of ¢ $e should not be prodixced by prematir 


can be controlled by the : 


Scan Devices 


Virtually any ae of device that provide 
video cameras, flat bed and slide scanner 


2 All the details about the scanning mechanism are described in a separate section entitled 
“Scanning”. 

3 Special patterns such as 45” lines, full page circular rings, diamonds, proprietary dots and so 
forth can all be added directly to the image iself. The results of this operation when printed 
are much more favorable and the whole mechanism is more device independent. 


€ Registered / Restricted Print and Imaging Overview 15 March, 1990 241-4 


s 


Scan Image Links 


Because input images typically run in very large sizes (up to 240 MegaBytes or more depending 
on size, resolution and quality requirements), input fragments are not stored more than once. 
Images are not copied in totality into every place they occur, rather an image reference or tag is 
attached to the relevant data before it is attached to the document or application where it is 
used. With printing in particular, when images are encountered in a document being printed, a 
link* to the image in question is placed in the spool file rather than including the entire image 
itself. 


Printing 


Now let’s talk about the Printing model. 


unburden the appli 
process pages at lei 
metaphor is a pipe 


The Printing 


printing: the docum 
sthree of these i in 


but are documented more ther 
relationship of the three team 


4 These links should not be confused with shared document links as they are not the same thing. 
The links described here are more low-level and invisible to the ordinary user. 
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Appl on - Print Server “<Grmmencemmayp,| TEAM 


Document 


Printing a 
Classes [- 


Intermediate 


A MANAS SASS MUMMERS VAAN APR 


components of printing. The Printing Clas 
accessed by developers. The Print Server o: 
re of printing on a specific printer, 
ae s indicate the flow of pr 


throughout ¢ 
Printing Clas: ‘: 
both of which function in the 


PageSetup Og; : og: "These 
dialogs are minimal a ave very few built-in functions already in them but the first two may 
be augmented by the application if desired. All are necessarily device dependent. 


There will be more about the user interface to printing as the Pink Human Interfaces become 
more mature and well defined. 

Printing Devices 
We must say a word about Print Devices. Graphic input-output devices may be divided into two 
categories, Primary and Secondary. The deferred printing model is intended for Secondary 
types of devices as defined below. Primary devices are handled more directly and usually by 


other means than printing. 


Primary devices are: 


¢ Always there, that is, always attached to the machine, for example the monitor. 
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¢ Fast and responsive and are most likely used interactively. 
¢ Typically “near”, meaning within the client’s own address space. 


Secondary devices are: 


Intermittent or dynamically connected; not always on-line. 
There may be many such devices from which one or two are chosen periodically by the 
user or application. 

¢ May be slow and probably not used interactively. 

¢ Okay to be “far”, or outside the client’s address space in other processes or teams, - 
maybe even physically remote. 


The deferred printing model can be thought of as a way of wrapping up a Primary device and 
converting it into a Secondary device. This will become more clear as we talk about Albert 
Graphics and Printing Classes 


Printing Classe 


There are two ae 
two classes, MPrin 
an Albert metap 


‘will make use of 


SR RO RR I CNR AOTC RIN OO RN a I IH OS ROR I ON SIC OC OO OR 


ST OOOO OT OOIEOSOUCOCOCI ODDS SOUT TEN 


Figure 4. An MPrintable represents something that can n be printed. It can be mixed with 
anything that can be drawn in order to make it printable. 


Figure 5. A TPrintJob contains everything aboula panune<s session 1 that a document needs to 
print. Like a TGrafPort, it contains the state of printing in bundles called TPrintSettings and 
TJobSettings, somewhat like TBundles in Albert Graphics. 
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We assume that. the reader is familiar with Albert Graphics to some extent because we will 
draw an analogy between the graphic and printing interfaces: 


In Albert, an MGraphic is something that knows how to draw. In printing, there is an 
equivalent class that knows how to print called MPrintable. 


In Albert, a TGrafPort is the object through which all drawing operations are sent. In printing, 
a TPrintJob is is the object through which all printing operations are sent. 


In graphics an MGraphic is “drawn” into a TGrafPort, in printing an MPrintable is “printed” 
into a TPrintJob. 


It should be noted that this analogy should not be taken too literally. It is not necessary, for 
example, to mix MPrintable with every object you ever intend to print. The metaphor is to show 
how they are to be used 


ne TPrintJob, though 
they will emerge i i , ntJob is to delimit a 


The TPrintJob'may:b 
Primary device channel) 
for Primary and Secondary de 
either printing or graphics. 


When an application is prepared to print 
into it. It isa good idea for the applicati 
although nothing in the Printing Classes 
be autonomic the main application b. 
j ting session with. 


inder without involving th 


ages are drawn by an application, th 
spooled into an intermediate file, or piped directly through memory, to a specific Printer Team. 
The application is not aware of what actually happens to the data. This is usually of no 
consequence to the application except that a printable object’s drawing routines may be called 
more than once during the printing session. If this is a problem for the application and the 
application is not able to handle multiple drawing calls without undue burden, it may create a 
TPrintJob that only calls drawing routines once. In any case, multiple draw routine calls will 
almost never occur in practice except under low disk space conditions. 


> This method of background printing should not be confused with the deferred printing or 
background printing model as provided by the printing architecture. Whether or not the 
application calls the PrintPage member function in a background task is up to the application. 
The actual physical printing of the document on the printer always occurs in the background. 
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The Print Server® 
Now let's talk about the Print Server. 


At the commencement of a print job, the Print Server is notified of the pending job. The Print 
Server has the responsibility of coordinating all print jobs and to make sure they get printed on 
the proper printer. The Print Server dispatches a Printer Team to print each print job. If 
printers are busy, it makes a queue for the job and waits until the printer is free. 


The Print Server is not connected in any of the data paths and does not directly receive nor s 
transmit any printing data. It does not interact with the application in any way other than 


to redirect print jobs to different print 


master switch point forehe 


18,9) 


Printer Teams’ 


Printer Teams are th po deferred printing m Teams are 
actually miniature applications whose job it is to take a print job on a specific 
i ry printer specific and correspond to th it Driver in the 


“are extensible and 


r, because they are independe: 


attached to real devices. Device 
remote printers, conversion engines 


During the printing process, several Prin 
restriction on the number and kind of Pri 


Til. WE 


standing of the overall printing 
as. This action presents some user scenarios and de 
works from the perspective of the application and the user. 


6 The Print Server is documented in greater detail in a separate section entitled “The Print 
Server”. 

7 For more information about the Printer Team and its classes please refer to the separate 
section entitled “Printer Teams”. Printer Teams for special purposes or specific devices can be 
designed by third party developers as described in that section. 
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Printing Services 


Creating Documents and Assigning Printers 


For the purposes of printing, a document is defined as anything that can be printed. Usually it 
is partitioned into several pieces that correspond to pages, but this is not a rigid rule. A 
document may be assigned several properties, or settings, such as page dimensions, media 
preferences, orientation, imageable area, initial printer type, media size and perhaps output 
requirements (stapling, collation, and so forth); these may correspond to some intended target 
printer, or not, depending on the application. The application or user has complete flexibility 
to alter or specify any desired media format, whether it exists or not. 


Pages within a document may be assigned diverse properties that are unrelated to the rest of 
the document, making it possi O ing page sizes, for example, within a docum 
d with the document independent: 
onery pads may be created as:dc¢ 
ristics already embedded: 


templates, with p 
course, is at the 


Printers, too, ha 
characteristics. 


, color and font 
rties are matched to 


Page Setup, : 


There are twd 
dialog and 


When the properties of a documeén 
the PageSetupDialog on a printable ob: 
for the user. Subsequent to, or instead 
make additional settings or changes. 
interface if preferred. 


Dynamic pr hat exist only throughout 
Such conditions:m for default settings from job to job, but are : 
conditions. Examples of these settings are: number of copies, section and page range 
alternatives, destination (another opportunity to choose a printer), collation, input and output 
bin selections, and background notification. User authentication or verification can also be 
performed at this time. 


During this phase the application may use the PrintDialog method provided by the system or 
provide its own. 


Printer Selection 


The printing architecture allows printers to be chosen by a user and attached to a document. 
The chosen printer can be set by default for the entire system or it can be directed to a specific 
document. In fact, different printers can be set for every page of a document. 
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A printer may be selected as either the current system printer or as the printer for a specific 
document. The target printer for a document may be chosen at creation time or any time up to its 
actual printing. 


The currently chosen printer is available to a client in the MPrintable class.. When a printable 
object is constructed, a default printer is provided for that object (the current system printer). 
Subsequently, the default printer may be replaced or changed by the client or the user through 
the PrinterSelection dialog. 


Printers can also be selected on a page by page basis. This service may be necessary where 
certain pages of a document require certain features of a specific printer. Printing a single 
document to multiple printers is treated as multiple jobs as far as the printing architecture is 
concerned, but the client need only instantiate one TPrintJob and doesn’t have to worry about 
which pages go on which printer. Printing to multiple printers can be temporarily disabled 
when printing draft copies. 


Once a printer has been ie printer remains attached to > tha ao 


exists or is no longe 
user may specify 
either case, the u 
new printer, or to. 
not specify this ev 
standard list of 


kipped, scaled, tiled or clipped to the new, ; cs. The user need 
tim rinting occurs, either, since these 


Managing Pri 


There is one other user diale 
print job has been dispatched to'th 
user. The JobStatusDialog allows all 


Possible job status properties that may 
aborted, failed, or deferred. It is also pos 


the availabilit as disk space. 


Other Services 


Another service provided by printing is job accounting or transaction logging. This service may 
be augmented by a Printer Team, an application, or remote printer application. Please note 
that there are no security measures built into the printing architecture and none are planned, 
but the ability to monitor printer acquisition and usage is allowed. 


Multimedia 


The buzz word of the day is multimedia. While it is not the intent of this architecture to 
implement a full multimedia toolkit or application framework, it does provide a multimedia 
input and output interface integral to the system upon which an application toolkit can be built. 
By virtue of the developer Printer and Scanner Team mechanisms, third parties are able to 
couple their own devices into the system using a standard interface, without having to design 
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one from scratch and without having to integrate it into every new application that comes 
along. 


How does sound fit into the scan and print architectures? 


User Interface Samples 


These will be included at a later time. 


IV. Print Classes and Objects 


The Printing Classes 
are not familiar with 


fir d 


e printing architecture section abo 
‘6 that section. 


MPrintable_ 


MPrintable is a bas¢ class mixin that provides primary printin 
application gains.access to all printing facilities. In order to ma 
be mixed with tabl 

simplistic but 
about printing 


Phrough it an 
4 printable, it must 


TExamplePage 


MPrintable is designed to provide a complete printing framework where very little work needs 
to be provided by its clients. Or it may be treated as an extensible architecture where many of 
its services are overridden to obtain exactly the printing model desired. The default model is 
described first and then in more detail how it may be modified for greater flexibility. 


The MPrintable base class may be applied to whole documents, single pages, individual 
graphics or to anything in between. Any object that descends from MGraphic may be printed as 
a document in its own right, provided it is mixed with MPrintable. As new components or pages 
are added to a printable object, they too may be made printable simply by mixing them with an 
MPrintable and adding them to the superstructure. Because each component has an MPrintable 
object associated with it, each one may have options that vary from component to component. 
There may be any number of MPrintables associated with a document, one for the entire 
document, or one or more for each page. 


class MPrintable : public MCollectible { 
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public: 
MPrintable(); 
virtual ~MPrintable(); 
virtual void Print(TPrintJob&s printJob) = 0; 


° e eo 


}; 


The easiest way to make a printable thing is to create an MGraphic, add MPrintable to it, and 
use the draw methods of the MGraphic to print. This can be done manually if desired, using the 
MPrintable from above, or clients may use the MViewlsPrintable class which can be mixed 

with any TView to make views printable. You don’t need to override the Print method because ~ 
the printing system provides one that should be reasonable enough to use. The class does all the 
work. 


class MViewIsPrintable : public MPrintable { 
private: 
TView% 


public: 
(TView* viewToPrint); 
e() 


A general document is conceptually simik 
that the hardcopy form is a representatio 
within the mind of the user assisted to so 
documents mi : 

content of € 
set of page: 
is specified 
sequence. 


the available media 6: 
ad by the printer to main 
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TPrintThing 


Cate 


T...Document 


covers some Seay large area 
a page. A spreadsheet or large graphic 


This model is necessarily restricted to a c¢ 
this model will serve a variety of applica 
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T...SpreadsheetModel 


T...Document 


The Spreadsheet modeler 
f3 


‘A Me, . % ‘ ¥ ces 
PN OR 4 4h3sspiprggesc: 


Figure 8. The S del. Mixi i it w makes a convenient 
spreadsheet moc 


Another possible choice for default 

by a separate MGraphic of the same s 
model more suitable than the spreadshet 
restricted to a uniform page size for all pa 


In the Stack model pages are uniform in sizeandany number in length. In contrast to the Spreadsheet model 
the pages have no metric relationship to each other and each page is positioned at the logical origin. 


SU MANES NINN a SORE 


Figure 9. The stack model requires only one MPrintable to represent the entire document. 
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Pile Model 


This model is somewhat similar to the Stack Model except that the pages may have varying 
sizes and different orientations, and all the pages are stuffed into a sequence. 


T...PileModel 


T...Document 


Sa a A AR i ES EN, OE IRC SRD ICH MN AN yn ORM Dy GH RTA ICA KR IG CG 


provide. The 
sequence. 


Other Document 
It is possible for the application t 


design. Completely arbitrary printing’: 
examples, may be supplied as well. In : 


Are there other default models we shoul 


ith printing is TPrintJob. I 
job based on the print params each page. It has many of the : 

familiar PrintRecord from classic Macintosh printing. There is really no interaction from the 
client required for this class except that the application that is doing the printing must 
instantiate one of these. (We could do this automatically but we may provide other services in 
the future which dictate that the application do this.) 


Figure 11. The TPrintJob class. 


TPrintJob corresponds to one printing session and exists only for the duration of one job. All the 
paraphernalia required for a printing session, its state parameters, grafport, and document 


information, is handled by this class and every print job must have a TPrintJob associated with 
it. 


class TPrintJob { 


private: 
TPrintSettings* fDefaultPrintSettings; 
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TJobSettings* fDefaultJobSettings; 


public: 
// This will eventually be used for printing animation frame sequences as well 
void PrintPage(MGrapnic& graphic, TPageSettings& pageSettings); 
void PrintPage(MGraphicé graphic); 
Get /SetDefaultPageSettings(); 
Get/SetDefaultJobSettings(); 


}; 


The fundamental member function within a TPrintJob is PrintPage(). The graphic that is 
passed to it packages the entire graphical content of the page inside its “.Draw()” call; that is, 
asking this graphic to draw will result in it drawing everything on the page. Note that a 
client won’t necessari to-go out-of her-wayto create such a package around the 
of a single page, becat drawn on the screen in a TVie 
TView is already th is what is used when printi 
view” (see MViewk 


We can also see in 
printing system. = 


class TPrint$S: 
private: 
TPageArea 
TMediaType fMediaChoice; 
TDoubleSided fDoubleSided;®: 
TPuntOptions fSkipTileClipseé 
TOrientation fOrientation; © 
TSourceTray* fTraySelection; 
TDestinationBin* fBinSelection 
TS ; fSettings; 


sizes don' 
ence 
source or de 


// Addition defined set 


public: 


ntSettings (); 


/* More Stuff */ 


Here is what TPrintJob does. Associated with a TPrintJob is a TGrafPort that is like the classic 
Macintosh GrafPort, but it is hidden from the client. When TPrintJob::PrintPage is passed a 
graphic, it tells the graphic to draw itself into this private port (possibly multiple times, for 
instance, to do banding). 


The private printing port is a standard Albert TGrafport. However, it is connected to a special 
“spooling” TGrafDevice called a TRecordingGrafDevice. This TRecordingGrafDevice is 


associated with a TSegment, the classical “spool file”. Rendering calls to the TGrafPort are 
encoded and written to this TSegment. 
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Support Classes 


TStreamingGrafDevice 


To “despool”, the 
streaming /unstre, 

“spool file” does 
member functio 
printer TGrafD« 
supplies such 4. 


'ice’s “output jack”, 


despool it, rewind the spool file 
The following classes make up the part 


chosen to refer to all types of P 


Media Classes 


Media is the term used to specify what a document page will be printed on. Media is 
characterized by a size metric, an ID, and a human readable name. The name is localizable, 
that is, it may be altered for local languages where appropriate. The identification token 
serves to distinguish every media type from every other, even if the name has been localized. 
Real printers have at least one, and perhaps many, media types and one class associated with 
each type. Printers are allowed to have any number of media types. (See Printer classes 


below.) 


Matching media types between different printers is done first by ID and then by size. 
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TMedia may be subclassed to provide more detailed pean to the document, such as film 
type, gamma index, tone reproduction curve, and so forth. 


Trays and Bins 


Closely associated with media type is the input tray, or source of the media; and the output 
bin, or page destination. Notice that the word “tray” is used to designate input sources and the 
word “bin” to designate output destinations. A tray or bin may be logical entities, meaning that 
they do not have to represent actual hardware on the printer. For example, two types or two 
sizes of paper may actually originate from the same physical tray, but logically they are 


treated as two trays. 
TDestinationBin 


ania altered to nia 
es or field upgrades. 


Trays and bins 
Some instance: 
interchangeabl 


The next logi¢e 
these collections to represent 
can be dynamically altered to aff 
between the collections and a phys 
may sometimes be unspecified and th 


Trays have an imageable area associated 
limitations of the printer in printing all t 
i the total media area. 


of media tra 
orientation of the i ‘pag 
Media orientation is defined with respect to the direction of travel of He media through the 
printer and how it lands in the output bin. Image orientation is superimposed over the possible 
media orientations to generate eight possible configurations. This allows the user to see exactly 
how the image will appear with respect to the media as it is placed in the printer input tray 
which is really what she wants to know anyway. 


Iconically, orientation may be represented as shown in the following figure. 
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ee 
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rey 
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Figure is Pos SOCGTACOTIOTTS BOT SOUTER? ot rinting device. ; 
The possible ori 


typedef enum “NarrowLeft, WideUp, 


of the media: 
completely interchangeab 


Stacking order describes how pagés'a 
printed pages. Possible alternatives | 


typedef enum StackingOrder { Faceles 
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SSeSSS 


pe 
following figure’sh ition of duplex printing, but in’th 
applies to the most ed side of the current page as it faces st printed 
side of the previous page. Face-out is just the opposite, the earliest printed side of the current 
page faces against the last printed side of the previous page. 


When duplex or double sided printing is available, it is important to maintain the page order 
between the two opposing faces. A duplex tray therefore has a sequence associated with each 
page of media it delivers. This must specify how the second face must be printed in 
relationship to the first face. For example, it could be immediately following the first face or 
after all first faces have been printed. 


TDuplexOrdering 
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SN 


Figure 15. Duplex pritt 
(b) Face-Out (c) Facele: 


In this diagram we are tacitly assuming th 
printed side in order for our definition to: 3 


considered comp] 


When a document is created the media size and format for each page are specified either by 
the application or the user. At print time each page of the document is matched with the 
appropriate input tray and the proper destination bin. The criterion for matching document 
pages to input trays is media size, type, and whether or not manual intervention is required. 
For bins the criterion for selection is collation, finishing needs such as stapling or binding, or 
whether a specific address is required such as a mailbox. The ultimate selection can of course be 
manually overridden. 
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Printer Classes. 


The class that represents a real printer type is a generalization of many printer characteristics. 
Printers are a conglomeration of several other classes; a GrafDevice, media, and Tray and 
BinOptions. A printer.choice.dges not have.to.represent an actual printer. It may be a logi: 
printer or represent a ted to the users machine. Printer.cl. 
dynamically allocate ted printer or currently opened: 
(which has a select : 


Printer Addresse 


ocation. This 
not (yet) able to 
entification for the 


within themsé 


class TPrinte 
public: 
it exists 


TName& GivenName(TName © 
TName& ProductName (TNameé) : 
long PrinterID(); // U f in the wor 


}e 


A printer address:consists of several desci 
scorrespond to the 


Printer Attributes 
In addition to addresses, printers also have attributes. 


class MPrinterAttributes : public TPrinterAddress, public TTrayOptions, 
public TBinOptions { 
protected: 
long Version(); // Returns the version number of this class 
TPrinterAddressé& Address(TPrinterAddress& address); 
Point& Resolution(Point& DeviceResolution); // Pixels/in2 
TDuplexity DoubleSidedPrinting(); // one or two sided printing 
Scan FieldofScan(); // Direction, Raster, vector... 
Cardinal FieldDepth(); // Bits per pixel per color 
GraphicModel ImagingModel(); // QuickDraw, Albert, PostScript, raw... 
ColorModel ColorModel({); // noColor, monochrome, spotColor, full Color.. 
Color Background(); // white vs. black... Default background color 
ColorTable ColorMatching(); // Color gamut of device 
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}e 


The attributes class is a mixin that provides device information about the attributes of a 
specific printer. Normally the application does not access these attributes since all 
information necessary to format a document is either accounted for in printing or is provided by 
other means. All of these properties are mentioned here for completeness. 


Device Access 
Device Access refers to a users privilege to acquire and use a printer for printing. In most cases 


users are always given access, but in a controlled environment where monitoring or charge 
accounting is required, access may be logged through this class. 


Access to printing devices is controlled by MAccess, a mixin provided to coordinate access toa 
logical printer. Default.access.is always 


initially.wide open to everyone. Applications,.. 
Estrict access to certain devices by... 
ass. The access class is not i 


Printer Teams, or othé 
implementing an acc¢ 
provide the ultimat 
add on flexible ext 


class MAccess { 
public: : 
virtual 


e e e 


s(Name, Password, IDNumber 


}; 


Logical Print 


class TLogicalPrinter : publi 
private: 
TID fIdentity; 


Setting up a yI MGraphic 


To accomplish printing, the client creates a MGraphic from which she desires to obtain hard 
copy. This may be an ordinary window view or some other combination of MGraphics. One 
possible example is a view created from a TView class and an MViewlsPrintable as follows. 


class TPictureView : public TView, public MViewIsPrintable { 
public: 
TPictureView() : TView(TGPoint (1400, 1400), TGPoint(0.0, 0.0)), 
MViewIsPrintable(this) {} 
virtual ~TPictureView() {} 
virtual void DrawSelf(TGrafPort *port); 
\; 


In this example, the only thing the application has to provide is the DrawSelf method which 
is just the same stuff that the view draws. The same drawing routine that draws to the view 
can be used to print. 
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Paging 


This example does not take into account the paging model for the view. Normally, the view 
may be associated with a single page, part of a page or many pages depending upon the model 
the client has in mind. In this example, paging is not taken into account, but the view could 
represent a single page, or any number of pages with the same print settings. If the view is not 
the same size as the output page on the physical printer, printing will still be performed, 
however the page to document wysiwyg correspondence cannot be guaranteed. The client has 
three choices for the output format when this occurs, the final output can be scaled, tiled, or 
clipped. The clients choice can be registered by setting TPuntOptions in TPrintSettings by F 
calling SetPuntChoice with an argument of kPrintTiled, kPrintClipped or kPrintScaled. The 
default choice is kPrintClipped. 


Scaling forces the view to be scaled to the output size of the page, while tiling causes the pages 
to be partitioned into a uniform grid the size of the printable area, similar to MacDraw. 
£ 


Programmers, take r 
document layout. ThA 
resolve conflicts be 


gPictureView->Print ( 
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I. Introduction 


The contents of this section are best understood if the overall printing architecture is already 
understood. Please refer to the “Printing and Imaging Architecture Overview” section. 


We begin by referring directly to the Print Server class, a subclass of MServer, and to its client 


MClient. 


POOP OOP HOR eee 


server through 


‘directly instantiate a TPrini 
all However, the structure and o} 

here so that clients can appreciate how the Print Server functions. 
The Print Server is relatively transparent to most applications. Most of its services are 
provided through upper level classes or from other services in the system, however, it is 
possible to communiciate directly with the server if need be. 
The Print Server performs five basic functions. 

¢ Provides a hierarchical list of available printers accessible to the system. 

¢ Provides a list of Printer Teams that are dedicated to specific types of printers. 


¢ Provides a client alterable list of print jobs for each printer. 


¢ Queues print jobs for dispatch to each Printer Team (and eventually to specific 
printers). 
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e Displays the print job queues for the user to access. This is the only foreground activity 
peformed by the Print Server. 


The sequence and priority of the items in the print job queue can be arbitrarily altered or 
reordered. Some items can be frozen or made to require a password and authentication before 
alterations are allowed. Clients making such restriction on queued items must be authenticated 
before regaining access. Restricted items can also be prevented from being processed until 
authentication is provided. 


The queues created by the Print Server inherit from the basic deque and collectible classes. 


TPrinterltem ok TPrinterDeque 


tPrintJoblItem 


Figure 3. The Three Queues 1 
and Printer Teams. 


There are thr queues, one for print 
applications e for Printer Teams w 


ll. Arc! 


The Print Server is a stand alone team of tasks that is initiated by the system at startup time or 
by any application that accesses printing services. When the Print Server is first invoked, it 
goes through a flurry of activity checking for consistency among all the printers, Printer Teams, 
and queued print jobs, after which it settles down to leisurely replys to requests for services. 


If for some reason, such as a power failure or emergency shut-down, print jobs are left 
unprocessed, these are found by the Print Server at system startup and returned to the 
appropriate queue for processing. If the job cannot be processed for any reason, the user is 
notified and the job deleted. 


The services provided by the Print Server, as outlined above, may be grouped into three 
categories: 


supplying lists of printers, Printer Teams, and print jobs. 


* providing a user interface through which clients may alter job queues. 
¢ dispatching print jobs to idle printers. 
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We'll examine each of these categories a little more in the following sections: 


Printer, Printer Teams, and Print Job Lists 


Print Server 


A CR WN WS SN NA Aa RA EN 


interface for doing these op 
Printer Teams are not directly alt 
the print queues, however, may be alte 
appropriate requests to the server. Norm 


the application prints, but applications w 
directly, provided, that the requests are no 


Print Job Que 


The Print Job queue 2 is shown iconically i in the next diagram. 
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Print Server 
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The Print Server provides a user interface for presenting the systex 


or each one. The interface indicates the prin 
ted, removed, reordered, switched to diffe: 
i re is one queue for each pr 


nd allows jobs in 
duplicated, deferred 


even across W: 


Print Job Dispatch | 


The most significant job performed by the 
applications to the appropriate printers f 
this is done. 
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Print Job Notification is 
sent to the Server 


— 


Print Jobs are 
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When an application prints, notification i 
the application being aware that anything: 
automaticall 


III. How It Works. 


Printing 


The primary purpose of the Print Server is to dispatch print jobs to the correct printer. It does 
this by invoking Printer Teams, giving them a scheduled print job and assigning them toa 
specific printer. It performs coordination between all printers, printing jobs, and printer queues. 
It also functions as the master switcher for choosing between printers. It is not connected in any 
of the data paths as it does not directly receive nor transmit any printing data. It does not 
interact with the application in any way other than through the printing interface. 


To see how a job gets queued through the Print Server, we will run through a sample scenario 
beginning with the user in the application. 
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The user initiates a printing job in the application (by clicking OK in a Print dialog). The 
application begins the printing process by calling the Print member function in the printable 
class object. During printing, notification is automatically sent to the Print Server that a job is 
ready for printer queueing. The Print Server takes the job and dispatches it to the appropriate 
printer, invoking a Printer Team if one does not currently exist. The job may either be processed 
immediately or queued for later printing, depending on the nature of the job, the availability of 
the required printer, how many pages, the number of copies, the availability of system 
resources, and the capabilities of the printer. If the queues are full and all printers are busy, 

the printing application thread may be blocked until a printer becomes available or a queue 

slot is opened up. This normally never occurs unless disk space is used up. : 


Other Services 


Sette Ona tat Railay ttete! et ap catatate! 


Applications may qu« 
Queries may be madé 
any of the printers 


tation about printers, Printer Team. 


Side from the 


IV. Print 


A TJobToPrint represents p 

Printing architecture framework b 
Print Server and Printer Team need tok 
the Print Server when it is ready. 


Applications that do default printing no 
ices other than printing 
Printer Classes in t 


Since the opera 
by member functio1 
functions. 


class TPrintServerClient: public MClient { 
public: 
TPrintServerClient (); 
virtual void Hello(); 
// The next member function will undoubtedly change 
virtual void PrintAJob(TJobToPrint,...); 


virtual void PrintDialog(...); 

virtual void SetupDialog(...); 

virtual void MonitorDialog(); 

virtual void PrintAbort(...); 

virtual void PrintAbort(...); 

virtual void AbortAll(); 

virtual void PrintReschedule (TJobToPrint,...); 
virtual void* GetSystemPrinter(...); 

virtual void* GetDefaultPrinter(...); 
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Class Overview 


There are two ways to activate the Print Server, either print or instantiate a 

TPrintServerClient class object and call any of its member functions. If it is not already 

activated, the Print Server will be created, initialized and started. The request will then be 
communicated to the server for processing. If the Print Server is being invoked for the first time ~ 
there will be an initial delay while the Print Server goes through its initialization process. 
Under some conditions this could take several seconds. 


Class Member..Functions. 


TPrintServerClient 


the queue 


TPrintServerClient:: Sys 
specified for general ayeten efindng: 


TPrintServerClient::GetDefaultPrinter takes the given job on the given printer and places it 
in the queue of newprinter at new position. If new is zero it appends to the end of the queue. 


V. Examples 


To activate the server from é an application during normal printing, do nothing. Activation will 
occur automatically. 


Other services may be obtained with code something like the following: 
TPrintServerClient TellTheServer; 


TellTheServer.Hello(); // Make sure she’s running 


e e e 
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// Create or TJobToPrint (from a TPrintJob, maybe) and pass it to the server 
TellTheServer.PrintRequest (TPrintJob) ; 
/* 
Actually an empty TJobToPrint or any subclass 
can be passed as a job to the Print Server. 
All that is required is that the Printer Team for the 
printer in question be able to understand and decipher it. 
*/ 


TellTheServer.MonitorDialog({); // Show the user what we just did 


TellTheServer.AbortAll({); // Then kill it just for spite 


egiste estricte e Print Server 15 March, 1 = 
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I. Introduction 


Printer Teams are comprised of two components, a mini-application that drives printers anda 
shared library resource that provides user dialogs for that printer. When we say “Printer 
Team” we usually mean both, or it is obvious from the context which component we are referring 
to. If there are any ambiguities we will try to explicitly say which piece we mean. 


The “Team” portion is an autonomous team that executes in its own address space and controlsa - 
specific printer. The shared library portion supports dialogs and other user interface services, 
which are executed in the address space of the application. 


In colloquial terms a Printer Team is like a classical print driver, but it has the added 
characteristic of being a completely autonomous application, made up of any number of 
individual tasks (hence.a.team).and.it.operates.totally in the background. It is actually more: 
analogous to the ubiq: i t 
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Figure 1. Printer Teams drive printers. From the overall 
architecture, we focus on the Printer Team portion. 
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Printer Teams are like classical printer drivers. Each one can drive only one specific type of 
printer. Because they are autonomous teams, however, any number of them can be operating at 
once, even for the same type of printer. A Printer Team of that type is instantiated for each 
physical printer being used. 


A Printer Team receives its all its commands and instructions from the Print Server. When it is 
activated, it receives a single print job, which is usually contained in a Spool File created 
earlier by a document application. It processes the job, prints it on the device assigned to it and 
goes back to sleep. 


“What You See Is What You Get” 


A Printer Team is responsible for reproducing as closely as possible what was intended by the 
document application. This specifically means “WYSIWYG” fonts, graphics and color 
matching, within the capa g used of course. Each hardware devi 


has a specified font set d known reproduction characteristics: ¥ 
are characterized in £ rameters enable the Printer.-3% :transform 
any text string or gr ion available on the print ed in color, 


position, size and 


Printer Teams provide other functions as W 
raises a Page Setup or Print dialog, those r 
Printer Team «Printer Team acts like a 


Printer Selection 


The Printer Team also provides a selection framework, a way for users and applications to 
choose a printer. These are implemented as shared libraries and are used exclusively by the 
Print Server. The Printer Team selection package includes such things as personal icon, 
selection parameters, access protocol, and hardware connection. 


There will be a bunch more stuff on this to be announced. 


Ill. How it Works 


To understand how a Printer Team functions, we will present a simple printing scenario and 
describe what the Printer Team does within this process. 
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Suppose a user wishes to create a new document in some application. First she probably has in 
mind some particular type of printer for which the final printout is being targeted. The chosen 
printer is attached to the document by choosing PageSetup in the context of the current system 
printer or selecting a printer as a template for the document. The user then builds the document. 


When the document is completed, the user asks for the document to be printed. This is done in 
some iconic manner through a Print dialog, for example, which accesses the intended Printer 
Team, or by dragging and dropping the document on the intended printer icon. The print 
parameters may be modified directly by the application or through the Print dialog if the user 
invoked it. : 


When the user has made her printing choice selections the document is spooled to disk and the 
Print Server is notified of a completed print job. The Print Server catalogs the request, attaches 
it to the appropriate queue and activates the proper Printer Team to process the job. The 
Printer Team receives the streamed print job through a TRecordingGrafDevice and converts it to 
\d sound synchronization are performed 
mpleted the Printer Team notifies: 


SE 


Figure 2. Several Printer Teams ¢ can all ‘be ‘operating 
at once, supporting a number of different printers. 
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IV. Classes 


Application Documents Named Physical 
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Printer Teams 
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Defautt Printer 
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A Printer Team comprises several compa 
which type it represents, and a client ser 
despooling class associated with it. 


Figure 4. The 


TDeviceChannel 


A device channel is a standard interface for performing I/O between a Printer Team and an 
actual device. 
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The device channel is designed to provide a uniform output mechanism for talking to devices. It 
is designed to allow developers to simulate devices or create virtual devices for preexisting 
Printer Teams. This makes printing extremely flexible and customizable for almost any 
conceivable printing application. By this means, Printer Teams can be relatively small and few 
in number and where the major part of the intelligence is housed. The device specifics can then 
reside in the TDeviceChannel which can be easily subclassed and modified. 


Specific 
Device 
Team 


Standard Device Interface 
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Output from a specific Printer: fe 
device channel. The device charine 
independently and which are used 
Normally, this channel implements a sim 
specific printer, but it may be subclassed t 
transmission to remote printers, testing, sl 


annel also operates asynchronously, 


state or physical configuration of the printing device. Initialization 

simply initializes the device. 
class TDeviceChannel { 
public: 

/* The Data Channel */ 

virtual size t Write(const void* p,long Count); 

virtual size t Read (void* p,long Count); 

/* The Inquiry Channel */ 

virtual size_t RecuestStatus(const void* p,long Count); 

virtual size t RecuestAccess(const void* p,long Count); 


/* The Attention Channel */ 


virtual void Abert ()}; 
virtual Boolean Pause(); 
virtual Boolean Resume (); 
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/* The Control Channel */ 
virtual Boolean SendCommand(const void* p,long Amount); 


/* Sound Channel */ 
}; 


A developer may override an existing TDeviceChannel by implementing member functions for 
all four streams of the channel. The supplied routines are in essence a simulation of a real 
device but can actually do anything as long as the simulation does not alter Printer Team 
operation. 


TPrinterTeam 


The TPrinterTeam ma 
Server, prints them 


Team. It requests print jobs from: 


class TPrinterTea 
private: 
fPrinterAttributes; 
fColorMatch; 


// Dialog stuf henever we can come up 


ynamic mechanism 


public: 


interTeam(); : 


virtual TJobToPrint* 
virtual void 


e e « 


}; 


TRecordin 


TGrafDevice 


TStreamingGrafDevice 
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Figure 6. TRecordingGrafDevice is 
the class used to reproduce aprint 
job. 


@ Registered/Restricted Printer Teams 15 March, 1990 24.3-6 


This class essentially makes up the print job received from the Print Server. To “despool”, the 
TRecordingGrafDevice is passed to the Printer Team. The Printer Team does this by playing 
back the TRecordingGrafDevice object itself. A TRecordingGrafDevice has a place to plug ina 
real printer TGrafDevice to have the recording played into. The Printer Team supplies 
aTGrafDevice which knows how to play on its own specific type of device. 


V. Examples 


The Printer Teams primary purpose in life is to sleep. When it is awakened it works only to get 
back to sleep. 


The Printer Team is awakened by some unknown entity, usually the Print Server but that’s not 
important. The Printer Team goes through whatever initialization incantation it needs and 
eventually ends up req 
playback feature and g: 
killed by the Print 


TPrinterTeam 


// initialize and 
// do to the Pr 


incantate for anything special the Printe 
@xc for startup. 


// Request a 
TJobToPrint* 


// Print the 
theJob.Play (m# 


At this point the Printer Teart"ha 
document, page by page, by replayi 
specific TGrafDevice object is the maj 
device to device. This Team can be anytt 


To assist developers in writing Printer T 
standard GrafDevice conversions. These 
vice. Clients can insta 


is sent to the device ov 


When the document has been printed, the Printer Team must then notify the Print Server of the 
status of the document printing process. To register job completion, the client does something 
like: 


// Notify the Server 
printer.JobComplete(); 


// Then loop back and do another job 


s 


If there are no more print jobs for the Printer Team to process, the team just sleeps until one is 
received. 
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Introduction 


In 1450, Johann Gutenberg introduced Europe to the printing press and changed the world!. In 
the 1980's, Macintosh helped make desktop publishing a reality2. We've become very good at 
creating hardcopy. We've become too good: we are surrounded by much useful graphic and | 
textual information that is available to us only in hardcopy form. Even if a piece of 
information has an accessible digitized form inside the computer, once it is printed out and 
annotated with a pen it has new information existing only on that hardcopy. When there is a 
need to interface this information back into the computer, for the typical user today the only - 
available interface devices are the keyboard and the mouse?. 


Of course we can't save the world overnight. It may take up an entire week. The first 

important and reasonable step is to handle the scanning of images. The desktop scanner is our 
model scanning device. Most of this document (and hence our task) will concentrate on this; we 
will generalize to broa¢ here it is realistic. : 


Our Goal 


Our goal is to incr 
We would like to. 
devices as well as 
For this, we nee 


the role of scanning devices in our users’ 
n up totally new applications for perso 
elerate the growing use of scanners for 


puting experience. 
¥ attached to scanning 
photographic images. 


¢ Create a framewo6t 
scanning is reall 


Application developers, scanning hardw. 
the rest. 


We wont st t 


ing scanning easy a 
concerned fe) 


ing: 


lor 


design that is extensible or applicable to ot ds of multimedia 


Purpose of this document 


This is the first description of a scanning architecture for Pink. One of the primary goals of this 
document, therefore, is to warn you about what we are scheming and to invite you to become a 
critic. But please, no hitting. 


1 An ERS that begins like this can't be all that bad... [By the way, my original opening went 
like this: “The interface between the computer and the hardcopy world is so one-sided that it 
makes me sick."] 

2It's turned into a commercial: Run for your lives! 

3Plagiarism is not enough: We need computer-aided plagiarism (C.A-P.). 
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User's Model of Scanning 


Of course, we have the whole user interface worked out already. Unfortunately, it is top 
secret (yeah... that's the ticket). So we will have to resort to describing things with 
analogies using elements of the current classic Macintosh interface (declassified circa 1985)... 


But to get serious just for one moment: The purpose of this section is to describe the spectrum of 
functionality that our design provides and to give a general idea of some envisioned user 
interactions. To give the description some concreteness, we will freely talk in terms of classic 
Macintosh user interface elements, but these particulars are the least important part of what-~- 
we want to say. 


Some User Scenarios 


Meet Typical User A. § 
101. Being an alwa 
relevant art books cg 
images she is going £ 


#riputer running the Pink system, whenever 
ame place: A iihcans system software u 


scan anything, she 
the Scanning Tool. 
thing: Running a 

ring up a single contro! 


operations, anc 
"preview" butti 
area. She selects: the 
and initiates a "real" scan. She 
to the destination in her docume 
representing the real image just scanniéc 
it into a scrapbook for safe keeping unt 
repeats this process to end up with a dozé 


_ Out pops 
re of the im 
will write lat 


Scanning Tool Scrapbook Document 


Fig. 1. "Scanning comes first" model 


(She figures she only has 5 pages of text to write now.) She is all finished with scanning the 
library books, but she defers returning them until the next day because Late Night with David 
Letterman is starting... 


4How to present the multitude of scanning parameters (like dpi, bit depth, etc.) to a range of 
users spanning a wide range of expertise is a nontrivial user interface problem. 
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Meet Typical User B. He is in the same art class and has the same paper to write. To his 
surprise, all the relevant art books (yes, the ones with the nice pictures) in the library are 
checked out by a person who signed with the name "Typical User A" (no relation to him). 
Armed with imagination, he creates the text part of the document leaving blank areas for 
where the images will go. He is so confident that he puts captions on those areas and has text 
flow around them. The next night, it is his turn with the library books. For him, the scanning 
process goes like this: 


Like Typical User A, he brings up our familiar friend, the Scanning Tool. He also brings up the 
document that contains the blank areas where the images will be placed. Of course he could just 
scan the images without considering the geometry of their destinations in the document; the _ 
document can do whatever scaling, cHpPHe: or reformating necessary to accommodate them. 

But he wants to scan it right the first time? (for one thing, reformating is out of the question 
because he wants to preserve his precious page count). 


The Scanning Tool has a preview area with a manipulable selection that indicates the "area of 
User. B.really.wants.to.do is make this preview selection the.exae 
: cae 


document; he push 
preview area of thi 
empty image is get 
this image. He c 
of course he can i 
the same link and 


‘through the link and 


inte 
' takes on that size ané 


ogically, an 
@ Tool is to "fill in" 
then position the selection (without changs 
wanted]) and do a real scan. The real im 


he classical 
em e 


instantaneous p 


After scanning into each of the vor 
There is plenty of time to watch L 


illed" Image 


Fig. 2. “Document comes first" model 


SIt is always going to be true that one is going to get the best results by scanning with the 
ultimate destination in mind (i.e. avoid unnecessary image processing runs like scaling). There 
is a human interface problem here as to how to make users aware of this fact of life. One 
possibility is to present an analogy between taking photographs and scanning: if a person has a 
lousy photograph, it is already occurs to him naturally that the best remedy may be to take the 
pHorogtape over. 

Part of the CHER document architecture. 


ee TUT annmnremmeer-aeeaereeee Trenance new _ _ emeneee-nen eee 
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Nothing precludes the hybrid case where a user has determined the geometries of the scanned 
image and the destination independently, i.e. a situation where you have, on the one hand, a 
scanned image of.one size and shape sitting in the Scanning Tool ready to be sent somewhere 
and, on the other hand, a document with a graphic selection ofa different size that is ready to 
receive the image. When you pass the image from the Scanning Tool to the document's 
selection, the image replaces the selection in the document in the same way it always works 
when you paste over a selection. What the document does in order to deal with a difference in 
geometries of the old graphic and the new image is up to the application. 


Summary of these user scenarios: 


¢ Users always go to the same facility to scan: the system Scanning Tool (there 
is no "Scan" command in each application). 
¢ The Scanning Tool can be used independently of any destination document of 
the images. 
¢ Scanning that is dependent in reasonable ways on the destination of the 
eis: pessible.and-handled in a natural way. 


Scanner 


rare Cut/Paste Path Clipboard 


Fig. 3. Hieroglyphics 


Let's decipher this diagram: 
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The Scanning Tool is an application ("Tool") supplied by system software that is used to control 
scanning hardware and produce scanned images. Producing scanned images 1s all that the 
Scanning Tool does, so it is very good at it. Although we do not preclude developers introducing 
specialized Scanning Tools (see Developer's Role below), the suggested model has the user 
typically turning to the "system" Scanning Tool. See the "Scanning Tool" section below for more 
details about it. 


The user scenarios above described how the Scanning Tool interacts with a document across a 
link (or cut/ paste). This part of the design is built on top of the CHER document architecture— 
most of the functionality we are getting here is built into CHER and we get it for free. 

Although we've drawn two paths between the Scanning Tool and the document, data sending - 
via clipboard and data sending via link are very similar. (The scrapbook mentioned in the user 
scenarios can be considered just another kind of document.) We will happily incorporate into 
our model future innovations in CHER and the general Pink user interface elements that will go 
with it. 


sft show how it is implemented. The:S 


The parts connected to 
; mner. The “real work" at 


Tool is a user interfa 
separate team, the S 
communication. In. 
to the scanner hard§ 
processing— what 
The Scanner Team 


one by a 


", it talks 


The connection 
"standard interfé 
(to go with the 
Tool. Also, we 
be specialized: 
application that needs/ 
enough to make its result of playin 
truly no different from the system $ 


How the Scanner Team is implemented 6 
unspecified. Ultimately, we will find co 
various kinds of hardware so that we wil 


The Scanning Tool provides the following: 


¢ Control of scanning and image parameters. 

¢ Control for initiating scanning operations. 

¢ Graphical and direct-manipulation control of output image geometry. 

¢ Capability for dealing with destination image constraints provided to the 
Scanning Tool by example with a blank image passed backward to it from 
the destination. 

* Shows relevant system and scanning status information. 


We discuss each of these in more detail next. 


?Note that the document architecture demigods speculate that the Pink clipboard may be 
capable of holding more than one scrap— it may be more like a scrapbook and make the 
scrapbook unnecessary. 

8You have my word onit. 
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For scanning and image parameters, we can list the following: 


¢ Resolution, i.e. "dots per inch". 

¢ Bit depth and halftoning/dithering? 

¢ Color model (e.g. grey scale vs color) 

¢ Transparency? — Here's a new one. Since "matte" is part of the Albert 
graphics model... 

¢ Output image size, location, shape (i.e. it can be non-rectangular), scaling, 
clipping. 

¢ Brightness and contrast. 

¢ Filtering, e.g. sharpen, blur. : 


What will definitely NOT be on this list is a choice of "image file format"!9 - 


Presenting a multitude of abstract concepts like "resolution", "bit depth", etc. is going to be a 
nontrivial human interf to handle this is to have a HyperCard- “lik 
tf d then have the interface adapt to 


documents: A single 
in the case where the 
nected by a link, the 
eis:automatically sent 


d image can be ea to many des 
ment and the Scanning: 


Graphical an 
"preview" area in 1 the user trie) 

drawing out shapes on top of the'prs 
image. 


depth, color: 
y scale, then 


: eT Tool can do with this infor 
there may bea "novicé” mode where these parameters are hidden. In this case, the tool may 
choose the parameters based on the blank image. In a “power user" mode where these 
parameters are visible and manipulable, the blank image may supply the default settings for 
the parameters. 


Status information relevant to scanning include memory (disk) space on the system and an 
indication whether or not scanning is under way. 


? Digitizing at low bit depths and halftoning/dithering so long before printing (or displaying) 
time can easily lead to lousy results, so it will be discouraged. However, this functionality will 
exist for low-memory situations (which should be rarer in the Pink virtual memory 
environment) and expert users who know what they are getting into. 

10There are two independent reasons for this: 1) How the image will be “stored” is relegated to 
the documents receiving the images. 2) The “file format" problem in general will be solved by 
Pink. 
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Open Issues 


Here are some thing we need to attack. 


Economical passing of images. Passing an image over a link or to/from the clipboard 
semantically involves copying the image. In the 98% of cases where the Scanning Tool is used 
to scan a single image that is immediately passed to a single destination document (and the 
Scanning Tool immediately throws away its “copy” of the image), we do not want to incur a 
copy operation in taking the image from the Scanning Tool to the document. 


Multiple scanning devices. How will we handle multiple scanning devices attached to a single 
system? One Scanning Tool for several devices? One to one? Several to one? If we choose to 
have one (or a few) Scanning Tools for many devices, we will probably implement "personality 
modules" for Scanner Teams: these are bundles of information that go with each specific 
Scanner Team (and its associated hardware) that describes anything special about it. One 
thing is for sure: This is a simpler problem than sharing printing devices because simultanegus, 
use of a scanner is imp pooling” mechanism. 


Software veloper 


Applicatio 


What does an‘ a3 
“standard” way to the wor 
application can deal with images a 
application can receive images from t 
If it can put out images, then it can influe! 
destination image, like it size, shape, an 


Specializ 


Developers '¥ attons that talk directly 
discussed in th ‘the interface to the Scanner ‘T' vat 
interface to the docum ased on CHER and is equally invariant).""'We hope that such 
applications are similar in character to the systein Scanning Tool in being small utility 
programs that do just the scanning task (and does it well) and not other tasks that can be 
separated from it 2 and that it makes its result available to other application via link or 


cut/paste. We would call such applications "specialized" Scanning Tools. 


canner Tea 
$Invarl 


The various classes that we invent to implement the system Scanning Tool can be made 
available to developers for use in creating their specialized tools. For instance, the preview 
window and controls may be something that developers may want to simply-"drop in" to their 
own interfaces. 


1lMaking a paint program accept scanned images will truly take zero effort; making the Alarm 
Clock DA take scanned images will take some work, even in the Pink system. 
12But since we can't prevent Microsoft from entering the game... 
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Scanning Hardware Developer 


To interface a scanning device to the Pink System, the hardware vendor will create a Scanning 
Team to go with it. For most mainstream devices, this will probably involve subclassing the 
classes used to implementa "generic" Scanning Team (provided by system.software). Creating a 
Scanner Team should be easy}. 


Optical Character Recognition 

In the case of scanned images, from a document's point of view, a Scanning Tool just appears as 
just another source of images— it could just as well be another document providing a "cut" image. 
Similarly, the result of an OCR scan is made available to a document as just another piece of 
text (or object-oriented graphic). 


The CHER link has a: 
several formats. It 
publish a type descri 
provide it as an ima: 


an where a data source can Offer its.dat 
ng Tool that includes OCR capa! 

ley yo document, I have thi: 
as an object-oriented gr 


There are several es in the architecture where OCR capabili 
software OCR engitie might be made part of the Scanning Tool 
image that the Sc&ining Tool scans. A lower level or hardw 
managed by a sp = ( 
tO pass on as usu: 


ugged in. A 

abe used on any 

R capability might be 
e to the Scanning Tool 


Fax 


The scanning architecture finds twe 
the "fax" object can be something that 
transmit it over the phone— it will be jt 
Scanning Tool. On the other hand, there: 
bringing it toa document. This problem ¢ 


fax inbox" obj 


similar to ou anning Tool!4. 


an interface to video sources like the camcorder. 


There are several properties of our design that we believe should be part of interfaces to other 
forms of multimedia input: 


* The user has one (or a small number) of small “tools” to control the input. 
* The interface to the document (CHER link or cut/paste) is one that is widely 
used by applications. 


13Nay, it should be fun. 

There are some fundamental differences: Running a "preview scan" is impossible (although it 
is possible to have a fax inbox tool that allows you to cut out just the interesting part of a 
received image and throw the rest away), choices concerning resolution, dpi, color model, image 
size and shape are more concrete. 
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* Applications do little (no) work to interface to the world of the input media 
source. 


Clearly our design can be extended or applied to any form of multimedia input where the input 
information can be packaged (or "recorded") into a static data object. We might summarize our 
general design as one that addresses the "media-to-clipboard conversion" problem. 


We recognize that there are multimedia sources where it is less appropriate to package the 
information into a static recording and where the information may better be described as a 
"continuous signal"!9, Clearly, in such a case our model is not fit or needs a fundamental 
extension. . 
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Microsoft Word!8. 


15tmagine a “TV Channel 4" object that I can paste (or somehow connect) into my document and 
watch the current broadcast of David Letterman in. 

l1€Qbject-oriented programming tip #11: Step 1: Subclass. Step 2: Take credit. 

17See previous note. 

18fust kidding— never mind. 
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David Letterman's To@ Ten Reasons to Scan 


10. Scanning is non-pollutionary 
9. What else are you going to do with that 300 gigabyte disk? 

8. 300 dpi... 150 dpi... 72 dpi... You decide! 

7. If we keep ‘printing’ without balancing it with ‘scanning’, then the 
universe gains a net accumulation of positively charged massless Q 
quarks. We wouldn't want that now, would we? 

6. It's (almost) as fun as a Xerox machine, but no one has gotten the 
idea of charging you to use it yet. 

5. It will NEVER run out of toner. 

4. In many states (and, in fact, in most nations in the European 
Common Market and Scandinavia), a picture is sti// worth a thousand 
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Timing Services 
Shinzo Watanabe, Patrick Ross, Deb Orton, Dan Chernikoff, Lee Bolton, Matthew 
Denman, Steve Milne 


COME IN TIME To 
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Introduction 


This document describes the timing services to be provided by Pink. There are four main 
components to the timing services, time (TTime), alarms (TAlarm, and TPeriodicAlarm), Date/Time 
services, and clocks (TClock and TRootClock). 


Terminology 


Time is a moment or period in some unit of TTime, such as seconds, milliseconds, etc. 


Time stamping refers to the action of using a time to stamp, or mark, a piece of data. This is useful 
when the time that the, © 


A timing service is the 
intervals, time stamp: 
calendar service, whi 


A time base isa re 


The hardware clo 333 ‘ovides a timebase that 
This can be used: ; ut if there is a nee 
representation 

Picture and Tel 


moval “shutiling” a video d i inimation in dith a 


alarms and inte represent various points in thm ts low for the 
representation of time in many different units, that can be used across different time bases. Time 
units can also be converted to other time units. It is therefore possible to describe time in units of 
seconds, milliseconds, microseconds, days, SMPTE frames, samples and more. 


Time Interval Model 


Time objects provide a convenient way to specify an instance or amount of time and providea 
mechanism for performing arithmetic operations on various time objects. Conversions between units 
(perhaps seconds to video frames) are also provided. Clocks are available for use as a time base, with 
the hardware clock being the most common (and default) clock. The time object (TTime) is 
subclassed to provide time ina variety of units (e.g. TMicroseconds, TSeconds, TDays, TSamples, 
TSMPTE, etc.) 


TTime 
Meth for General nsumption 
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Now CREATES a TTime object with the current time. It is a static member function of TTime. 
SetToNow fills in the object with the current time. 
Delay blocks the task for the specified amount of time. 


GetTime and SetTime set and get the TDoubleLong representation of time. 
ConvertTime convert from the hardware representation of time. 


TSeconds 
(A Sample of the TTime Subclasses.) 


r 
Operator double converts a TSeconds object to a double. Accuracy may be lost. 


TStopwatch 


{t returns elapsed tim. checked, can be 


last reset. 


Alarm Model: 


A task that wants to make use of the alarm services first queries a clock to get the current time. To set 
an alarm notification, the application does some arithmetic to determine the time at which it wants 
the notification to occur, and then creates an alarm object (TAlarm). The task to receive the alarm is 
specified when the alarm (TAlarm) is created. Once the alarm is set, the task goes on with its regular 
processing. Eventually, the task to receive the alarm does a WaitForAlarm call (in the case of an 
MMessageTask) or a Receive call to receive the message associated with the alarm notification. If the 
notification has not yet occurred, the task will block in the WaitForAlarm/Receive. When the alarm 
eventually goes off, the clock will send an alarm message (TAlarmMessage) to the specified task. 
The body of the message will contain the alarm handler object by the task which set the alarm, 
identification for the clock, and the time of the clock when the alarm went off. 


Note that tasks can set alarms whose notification messages are received by other tasks, and a task can 
cancel any alarm if it knows the original alarm (TAlarm). If the task that sets an alarm is terminated, 

that alarm is not canceled and will still cause an alarm notification message to be sent to the specified 
task at the appropriate time. Also, if an alarm is set for a time that is in the past, the notification 
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message will be sent immediately. 
TAlarm 


Meth for General Consumption 
The Constructor creates an alarm object and enables it at the specified time for the specified 
task. 

Equality Operator copies the alarm identifier to the new object. N o alarm is enabled (or dis- 
abled). 

Disable clears the alarm. 


Methods for Extending/Changing Behavior 
GetAlarmID returns the alarm identifier. 


SetAlarmID sets the alarm identifier. 


the alarm has been 


Ve 3 
ProcessAlarm calls HandleAla 
IsAutomatically Destroyed is true. 


Intervakan 


services are 


Interval Timing Model 


These objects provide a mechanism for drift-free timing of intervals. This class is based on the time 
objects described above. A mechanism for starting and stopping the stopwatch, as well as resetting 
and getting a “lap time”, are provided. 


Periodic Timing Model 
The periodic alarms inherit from the basic alarm object (TAlarm) and export a similar interface. 
These alarms operate given a start time and a period. Alarms are then generated from the start time 


and continue to be generated after the given period until the alarm is canceled. Periodic alarms take 
advantage of light-weight tasks (TAlarmTask) to generate the repeating alarms. 


TPeriodicAlarm 


This class implements an alarm that automatically fires at theStartTime and then again after 
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the specified repeat period until the alarm is disabled or destroyed. This class uses a light- 
weight task to implement the periodic alarm (TAlarmTask). 


The Constructor creates and enables the first alarm. 

The Stream Operators read and write the alarm id to the stream. 
Disable clears the alarm.. 

SetRepeatPeriod changes the repeat period. 

GetRepeatPeriod returns the repeat period. 

Assignment Operator copies the alarm identifier to the new object. 


GetAlarmID returns an alarm identifier. 
SetAlarmID returns an alarm identifier. 


ig a light-weight task. 


reates the task. Start must be called t 
SetRepeatPeriod:changes the repeat period of the alarni 
at period of the alar 


Main ehabl % ; 't alarm 
needs to be set. 


Clocks 


Clocks are the heart of the synchronizati 


code coming 
peaker). 


from a videotape recorder, or even from an audio object such as a speaker 
A clock measures the passage of time in fixed units (TTime). Clocks can run at uneven intervals, can 
speed up and slow down, and can even run backwards (e.g., all of these things will happen when a 
root clock is synchronized to a videotape unit that is shuttling forwards and backwards). 


There are two types of clocks: a clock (TClock) and a root clock (TRootClock). A clock is used to 
represent a local time base which can be used for setting alarms, and getting the time. Root clocks are 
used to synchronize to a source; such as the hardware timer, SMPTE, or someone's private software 
counter. One example, is the sound clock which is synchronized to a speaker (TSpeaker). The 
speaker can set a root clock's time every time samples are played. When a root clock is being set or 
controlled by a given source, it is said to be synchronized to the source. 


Rm 


TRootClock TClock 
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A clock can be connected to any other clock through a linear function. One of the clocks is the 
master, the other is the subordinate clock. The master clock can itself be controlled by another clock. 
In this manner, a chain of clocks can be connected with a defined relationship. A clock can only have 
its value changed by other clocks. Only a root clock may have its value controlled directly. Thisis * 
how a new time base can be created and implemented. A clock must be connected (directly or 
indirectly) to a root clock in order to provide its functionality. Pink will provide some built-in root 
clocks such as: MIDI clock, sound clock, and the hardware clock. 


It is possible then to define a relationship where alarms are set on different clocks all based on the 
same root clock. For example, three video clips that are played repeatedly, while synchronized to a 
sound and where the first video clip is to cycle once per sound; the second clip twice per sound; and 
the third clip four times per sound. The following clocks would be needed, and would need to be 
connected by the following functions: clock A in a 1:1 relationship with the root clock , clock Bina 
2:1 relationship with the root clock, and clock C ina 2:1 relationship with clock B. 


sound clock 


y 
needed would be to change clock'B 
All of the alarms set on the clocks w 


2:1 
B C 


The abstract relationship between time, alarms, and clocks allows for users to define timing in their 
own units regardless of their time base. For example, it is possible to write an animation sequence 
where different characters move at different rates. This may be controlled by setting Alarms in units 
of milliseconds, and SMPTE time code. This application could run on any pink machine, and could 
be controlled by any clock, be it a SMPTE clock, hardware clock, or sound clock. This allows for the 
user to control the synchronization of the animation with other applications. 


TClock has methods to get and set its value (the current time), stop the clock, start the clock, and to 
connect to other clocks. A single TClock may have to be accessible to many teams, probably through 
the use of CHER. A TRootClock has methods to update its value; this in turn causes the values of all 
of it's subordinate clocks to be updated. TRootClocks can also be made accessible to many teams 
through the use of CHER. . 
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MCommonClock 


MCommonClock is a mixin class that provides it's derived classes with a common interface for 
certain clock functionality, such as stopping and starting the clock; changing, getting and setting the 
direction; and getting the current time. MCommonClock should be used by any Clock related classes 
that need this functionality, with the same interface. MCommonClock is used by TRootClock and 
TClock, and should be used in any new clock designs. This class can be accessed simultaneously by 
multiple tasks. 


Meth for neral nsumption 


GetDirection returns a DirectionState that contains the direction that the clock is pointing in. 
DirectionState has two possible values, kForwards, and kBackwards. kForwards means that the 
clock's value is increasing (time is moving forward). kBackwards means that the clock's value is 
decreasing (time is moving backwards). 
SetDirection sets the direction.of.the.clock.ta.the.newDirection value, either kForwards or... 
kBackwards. (This als or the connecting function, ax.¢: 
t's masters, and - if it isn't)... 
to change from Forw 


Sp should only be 
on to destruction. 
‘a MCommonClock::Stop 


Clocks start 


Ahead means that the time is in the diré 
5 and is going forwards (the next value 
Times from 4 to 0 and 0 to -» are consider 
value being 4) then the time 6 to » are con 


at 


Fthe clock is heading. x i t5 and is 
6)'then times from 6 to o are ¢% ij : 

-onside hind. If the clock was going backwa 
then the time 6 to © are considered "behind", and 4 to -cc are considered “ahead”. 
operator== compares the time of the clock with a TTime and returns TRUE if the clock is at the same 
time as theTime and FALSE if the times are different. 


Methods used by TAlarm 


Always use TAlarm and TPeriodicAlarm to set alarms. Don’t call these member functions direct- 
ly. 


Now returns the current time of the clock. 

AddAlarm adds and sets analarm to go off at the specified time. 
AddPeriodicAlarm adds and sets a alarm to go off periodically. 
Remove removes an alarm. 

RemoveAll removes all of the alarms for that clock. 
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TClock 


TClock provides a timebase for setting alarms and timestamping. A TClock must be connected to a 
TRootClock (directly or inderectly through connections to other clocks that are connected to one). 
This alows clocks to run ina specifcly defined relationship to each other, and to be able to add 
alarms, and do timestamping thru a common interface. When a TClock is created it is automatically 
connected to the system’s THardwareClock (which is a specific TRootClock). 


Meth for neral nsumption 


SetFunction sets the function that describes the relationship between the clock and it's master clock. 
The function must be a linear function, where f(x) = ax + b where 'b' is the offset and ‘a’ is the ratio. 
SetFunction effects the time for the TClock, and therefore should only be called when the relationship 
between the connected clocks changes, and upon initial connection. An Example: If a TClock is 
being connected to another clock who's current time is 9, and I want my time to start at 0, and run 
twice as fast the connectien-funchon: would-be:2x:-.9. So the offset is -9 and the ratio is 2.. 
GetFunction gets the ¢ n f(x) = ax +b of the clock and.i 
ratio, and ‘b' is the of 
SetAtNowPlus sets t 
SetToTime sets the t 
SetNotificationTa 
clock, or one of it's asters, changes. Changed states of the clo 
direction, change it the function between two clocks, and the c 
called directly if 
SetValueTo chan 
and it's master s¢ 
function is f(x) 
off as if their ti 
example: if the 
new value of 1 (3 less than : 
time reaches 5 (8 -3 = 5). See SetAtN 4 hout 
effecting the Alarms. SetOffset should f 
changed and all previous alarms should 


irrent time (now) plus 


éd when the state of the 
pping, changing 

locks. This should be 

o the clock. 

3 ship perce the clock 


TRootClock ind n€lock. TRootClock implement: ther clocks can 
connect too. To impler he timebase, TRootClock's SetTime metho od tialize the time 
for the clock. Then MoveToTimePlus or MoveToTime are called to update the time “for the 
TRootClock. TRootClock is used to be the master of all other clocks connected to it. It is used by 
TClocks to connect to get different time bases. For example, a hardware clock, MIDI Clock, or Sound 
Clock, could all be implemented using a TRootClock. TClocks would be used to connect to it, set 
alarms and do other timing functions. TRootClock always expects to be used with at least one 
TClock connected to it. TRootClock is controlled by what ever device is providing the interface for 
the timing base. For instance, a TRootClock could be driven by a animation application that wanted a 
time base of it's own which it controlled it's own frame rate with. Alarms could then be set for 
TClocks that where connected to the TRootClock. 

Probably only one class will call TRootClock's methods. 


Meth for General Consumption 


MoveToTimePlus moves the time of the TRootClock from it's current setting to it's current setting 
offset by the value of a TTime in the root clocks direction. If the plusTime is negative the direction of 
the clock changes. This call is used to update a TRootClock to a specific time from the current time, 
all of the functionality of the clock is performed as if the clock was moved thru time to the new value. 
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All alarms between the current setting and the new setting will go off. For example if the clock is at 0 
moving backwards, and a plusTime of -3 is provided, the direction is changed and the time is moved 
to 3 (the clock will be moving forwards). 

MoveToTime moves the time for the root clock to a new TTime. : This call is used to update a root 
clock to a specific time, all of the functionality of the clock is performed as the clock is moved thru 
time to the new value. If the newTime is in the opposite direction of the TRootClock's direction, the 
dirction of the TRootClock is Changed. All alarms that were added for the time between the current 
setting and the new setting will go off. 

SetTime sets the time of the root clock to anew TTime, and removes all alarms set for that root clock 
by any of it's subordinates. This call should only be made when it is necessary that the RootClock is 
set to a specific time, or needs to be reset or initialized. This call is not to be made to update the time 
for the clock. 

GetResolution returns the resolution of the clock. This call should be used to help determine how 
accurate a clock is. 

SetResolution is used to set the resolution of a clock. The resolution is the largest amount of time 
that the clock may move through at one time. This call should be made to set the resolution winch 
can provide useful inf the-accuracy of a clock. 


i BS 


since 4713 B.C. # oe | 
interpretation é 7} Sys since 
the given origi 


Date/Time Model 


The date/time classes export the Julian Da 
day/night periods that have passed since 
implemented using an object representing 
difference bets o dates (TDateSecon 
date/time Al 
Calendar i 


TDateTim 


Constants 

kJulianOriginDate number of seconds since January Ist, 4713 BC at noon. 
kMacOriginDate number of seconds since January Ist, 1941 AD at midnight. 
kModifiedJulianOriginDate the modified Julian date. 

kUnixOriginDate number of seconds since January lst, 1970 AD at midnight 
kDosOriginDate number of seconds since January 1st, 1980 AD at midnight 


Methods for General Consumption 

SetToToday fills the object with the current date. 

Today is a static member function which CREATES an object containing the current date. 
operator double convert to a double containing the number of seconds. 

operator TDoubleLong convert to a TDoubleLong containing the number of seconds. 


Method in Implementation 
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HardwareToJulian convert from hardware representation to the Julian date. 
SetHardware initialize the hardware to the specified date. 


TDateSeconds 


This object exports all the TDoubleLong operators and provides conversions between itself and 
the built in type “double”. There are also conversion operators for TTime objects. 


Notes 


A little known, but highly useful method is provided called TwiddleMMU(). This method allows 
unrestrained twiddling of the MMU (Memory Management Unit) and is included as part of the alarm interface 
because the OS weenies found it alarming. Twiddling the MMU is especially useful when frustration levels are 
high and productivity low or when you have nothing better to do. 
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Time Ports and Sequences | 
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Architecture 


Time Ports and Sequences are used to help control the flow of time-related data. Examples of time-related data 
are 1) MIDI (Musical Instrument Digital Interface) data, which is used to control music synthesizers; 2) a series 
of frames in an animation; or 3) any data that is ordered in time. 


Time Data 


Time data (TTimeData) is a class that consists of two important objects - a time stamp and a chunk of data. The 
timestamp is a TTime object. The data is a TMemory object. TTimeData has methods to create, modify and 
compare time data. Time data can be used to hold MIDI commands, other non-MIDI representations of musical 
data, points of interest in an animation, or any other time-related data. The data part of a time data object 
must be understandable on its own. It must be intelligible even if interleaved with other data of the same type. 
For example, you cannot use the data to represent a MIDI command with free running status. 


Time Data Ports 


Time data ports (TTimeDat 
ports (TOutputTimePort) and can be écted input time port’ 
and TOutputTimePort are descendants of TTimePort. Time data ports ca 
source for the port. Output ports can be connected to input ports, proba 


amePort). TInputTimePort 
ck (TClock) as the timing 


Input Time Data Ports 


All time data objects that are read by an input po 
when the data was sent. If the input portis not u 
read from an input port:by.a blocking read, or a no 


‘Input port in another team. TOutp: as functions for using 
“Time data may be written to an output port by a blocking write, or a non 
blocking write. The blocking write will block the task until the time data has been received by all of the input 
ports it is to be sent to. 


Time ports can be connected to each other over a variety of different teams. There can be multiple connections 
from one output port going to many different input ports. There may also be many output ports that are all 
connected to one input port. Data flows from one port to another when an output port is written to. That data is 
then transmitted to any input port it is connected to. The teams that own those input ports can then read the 
data. 


An Example - MIDI 


MIDI data needs to have its time preserved by a time stamp, so that the rhythm information is retained. The 
MIDI data also needs to be sent at the appropriate time. A user may want to have MIDI shared between 
multiple teams. 
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Team A q > Team B 

laa é 
ee 
< 


In the above diagram, the MIDI port uses the serial port hardware to communicate with an external music 
synthesizer. Both teams A and B receive any data coming in from the MIDI port. This data is time stamped for 
them by the clock used with their input ports. Team B is.also receiving data from Team A's output port. This 
data will also be time stamped by Team B's clock. Team B is sent data from it's output port to the MIDI Port's 
input port. This data is sent when Team B's clock is equal to the time stamp for the data to be sent. Team A is 
also sending data when it's ou! it.is.time to be sent. Team A's data is sent 
the MIDI Port's Input Ports. 2 


Time Port Editor 


graphical editor. Such an 
or the Macintosh. This 
‘ports. End users can patch 
and powerful tool for 
same.similar way of doing 


In MIDI applications, it is 
editor is supplied with the 
editor, called PatchBayt 
the time ports together i 
musicians, who are used 
this for all time ports i 


AIDI Management Tools currently provid 
sraphically depicts applications and thei 


al. MIDI cables togethe 
JER. 


Sequences 


Time events can be collected into an ordered 
any output port for that team. When a sequen 
time data ports at their scheduled time. A Sequ 
these ports can be recorded directly into a sequenc 
Pink. Possible uses of Sequences would be for imp! 
runs MIDI, animatiat und effects. 


MIDI 


Pink provides a MIDI Driver that works with the Apple MIDI Interface and compatible Interfaces. This 
driver has two data ports, one for input one for output. Time data objects that contain a MIDI command for the 
data can be written to the input port, and will be sent to the MIDI Interface. MIDI information coming in from 
the MIDI interface will be packaged into time data objects as whole MIDI commands, and will be time stamped 
using the MIDI clock provided with Pink. Multiple output ports may be connected to the MIDI input port, and 
the MIDI output port may be connected to multiple input ports. 
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Classes 


TTimeData 


TTimeData is the main object used with TimeDataPorts, it is the object that is passed between data ports. 
[t contains two parts: a time stamp (TTime), and a chunk of data (TMemory). It has methods for getting 
and setting the time and data. It also has methods for comparing it to other TTimeData objects. It should 
oe used whenever use of data ports is desirable. 


class TTimeData: public TTime, public TMemory{ 


public: : 
MPersistentMacro (TTimeData) ; 
TTimeData () ; 
TTimeData(const TTimeData& aTimeData) ; 
virtual ~TTimeData(); 


virtual void SetTime (const TTime& theTime) ; 
virtual TTime } 
virtual void 
virtual TMemory . 
virtual Boolean 
virtual Boolean 
virtual Boolear 


ry& theData); 


a& aTimeData); 


ky 


void TTimeData::Se 
Sets the TTime of the 


TTime TTimeData:: 
returns the TTime of the TTitme 


void TTimeData::SetData(const TMe 
sets the TMemory of the TTimeData object to 


TMemory TTimeData: :GetData(); 
returns the TMemory of. the TTimeData. 


Boolean TTimeD : 
Compares the time © imesof aTi j 2 preater than 
the ‘aTimeData’. 


Boolean TTimeData::operator< (TTimeData& aTimeData) ; 
Compares the time of the object with the time of aTimeData object. It returns TRUE if it is less than the 
‘'aTimeData'. 


Boolean TTimeData::operator== (TTimeData& aTimeData) ; 
Compares the time of the object with the time of aTimeData object. It returns TRUE if the two times are 
the same. 


MTimeDataPort 


MTimeDataPort is a mixin class used to provide common functionality for the different kinds of time data 
ports. It has methods for flushing events and getting and setting clocks. 


class MTimeDataPort { 
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public: 
MPersistentMacro (MTimeDataPort) ; 
MTimeDataPort (); 


virtual ~MTimeDataPort (); 

virtual void SetClock(const TClock& portsClock); 
virtual const TClocks GetClock (); 

virtual void Flush (); 


}; 
void MTimeDataPort::SetClock(const TClock& portsClock) ; 
Causes the portsClock to be used by the data port for all of it's timing needs. 


const TClock& MTimeDataPort: :GetClock() ; 
Returns the clock that is being used by the data port. - 


void MTimeDataPort : :Flush (); 


they have been written to a tit not been 


read yet. 


TInputTimeDataPort 


taPort and is used 
wo methods for 


TInputTimeDataPort des. 
TOutputTimeDataPort te 
(ReadTimeData) and 


g TTimeData objects from a 
: a blocking read 


class TInputTimebataror 
public: 
MPersistentMacro(TInputTi 


virtual 
virtual const TTimeDatas’& 
virtual Boolean 


ta); 
virtual void ’ 


ReadTimeData is a bt It will return a read ard: ‘to the next 
available TTimeData. one4S°-not-immediately available, it blocks the taskK*wntil<one is available. If the 
port is using a clock the TTimeData object is time stamped with the clocks value when it is read. If a 
clock isn't being used a time stamp of zero is used. 


Boolean PollTimeData(const TTimeData& readTimeData) ; 

PollTimeData is a non blocking read of the port. It will put a reference to the next available TTimeData in 
readTimeData if one is available. If one is not immediately available, PollTimeData returns FALSE; it 
returns TRUE if one was available, and is now referred to in readTimeData. If the port is using a clock 
the TTimeData object is time stamped with the clocks value when it is read. If a clock isn't being used a 
time stamp of zero is used. 


TInputTimeDataPort 


TOutputTimeDataPort descends from MTimeDataPort and is used for outputting TTimeData objects from a 


team ‘to the TInputTimeDataPort of another team. It provides two methods for writing TTimeData objects; 
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a non blocking write (SendTimeData) and a blocking (WriteTimeData). Most users will want to use 
SendTimeData. 


class TOutputTimeDataPort: public MTimeDataPort { 
public: 
MPersistentMacro (TOutputTimeDataPort) ; 
TOutputTimeDataPort(); 


virtual ~TOutputTimeDataPort(); 
virtual void WriteTimeData(TTimeDataé& output); // Blocking. 
virtual void SendTimeData(TTimeDataé output); 


}e 


void WriteTimeData(TTimeDataé& output); 

WriteTimeData is a blocking write of the TTimeData output object. Output is either sent immediately if 
there is no clock being used, or is buffered until the time of the TTimeData object is equal to or less than 
that of the clock being used. When the data is sent, it is sent to all of the TInputTimeDataPorts that the 
TOutputTimeDataPort is connected to. The current task is blocked until the TTimeData object has been 
read by all of the TInputTimeDataPorts that it was sent to. This method should be used only when writing 
TTimeData objects, where the..speed...and..timing..of..sending the data is unimportant, but wher 
be input ports that may need: hich insures that they can_pro¢ 
in. The task may be blocked the input ports are ve 
reading the data at all. : 


siders, or aren't 


void SendTimeData (TT 
SendTimeData is a non b] ¢ t. Output is either sent 
immediately if there is n@ ¢lock being used, or is buffered until the e TTimeData object is equal 
to or less than that of th to all of the 
TInputTimeDataPorts tha not blocked and 
returns immediately aft Sed for sending 
TTimeData objects, ur 


eData& output); 
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Introduction 


The Pink Sound Tools allow developers to build applications using audio, music, speech, and telephony. 
The tools consist of a set of C++ class definitions and various hardware specific implementations for 
those classes. 


This section describes the architecture of the sound tools. The meaning of the word “architecture” refers 
to the design philosophy and a high-level description of the various objects, how they relate to each 
other, and what they accomplish. The programmer’s view of the tools is the main focus of this section. 


This section does not detail the definition of each member function of every object. The complete C++ 
definitions of the objects a ine Class descriptions. The architectur. hould 
remain relatively stable e ject definitions change. : 


this section, more th 
a one to four year il 
E tany of the objects | 
CPU power than today’s platforms. Digital: 
cessors can provide the required power 


There are an ambitious 
release 1.0 of Pink. This 
dovetails nicely with ou 
machines that have m 
instruction set (RISC) 


ady to ship with 
‘10n period. This 
nin real-time on future 
assors (DSPs) or reduced 


Design Go 


1. End-user focus. We need : 3 satis- 
fy customer's needs or wants. Our expe 
applications: 


* voice annotation 
© voice mail 
¢ soundtracks 
- © telephone 
¢ remote 
* voice con 
¢ sound feedbe 
e music synthe 


multimedia presentati 


2. Standard Application Programmer Interface (API). Developers need a standard API for audio, speech, 
and telephony so their applications will work across a wide variety of different sound hardware plat- 
forms. We need to provide for hardware independence. A phone answering application, for example, 
shouldn’t have to concern itself with what type of phone system the user’s computer is connected to. The 
tools should allow the application to work with any phone system as long as the customer purchases the 
appropriate hardware and object libraries. 


3. Simplicity. Sound is a new technology for many developers. The tools have to be easy for developers 
to use, or they won’t use sound at all. To borrow an overused but apt maxim, “Simple things should be 
simple, difficult things possible.” . 


4. Generality. Because sound in personal computing is so new, it is impossible for us as toolsmiths to 
predict exactly what the big applications for sound will be. Therefore design must emphasize generality 
and flexibility, so developers can create applications we didn’t think of. 


5. Extensibility. Developers will want to add new functions to our tools. Luckily, extensibility can be ac- 
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complished easily with C++ by subclassing objects. 


6. Scalability. A given sound application should run across the widest possible variety of machines. This 
is difficult with sound, due to its real-time nature. A speech recognition algorithm that consumes 90% of 
a RISC processor’s CPU time will not run ona Mac SE/30. Other algorithms can be degraded, however. 
For example, when mixing multiple sounds together, some sounds could be dropped. Where possible, 
we must provide graceful degradation. 


7. Synchronization. Often sound playback is most useful when combined with animation or video. We 
must provide a means for synchronizing sound to other system functions and visa versa. The sound tools 
use the Pink Timer Tools (chapter 2.5) as a basis for synchronization. - 


8. Standard interface for sound. We need to provide a standard user interface for recording, editing, and 
playing sounds. Such an interface would define the way that users edit sound, much like TextEdit did for 
text on the Macintosh. An editor can also be used by developers to create and edit sounds. 


9. Standard interchange fo 
standard formats for storiri 


10. Reliability. Our tool; 
different ways than most 
processes will want to 
System designers to in: 


cise the system in 
ount, as multiple 


is a real-time process, 4 
ids simultaneously ind tools and Pink 


Ad titasking must be ta 
sly. This puts a burde 


Overview 


The Pink Sound Teas: 
Telephony; Editors; and Soun 


Audio Objects (2.6.1) describes the archit i idi nd 
music classes descend. 


Sound, Speech,and Telephony (2.6.2) describ 
speech, telephony, and music applications. 


Editors (2.6.3) 


lasses used for itors. itor: ce for 
creating, editin Si 


Sound Effects (2.6. | effects library that will have to 
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Architecture 


Audio objects are the heart of the Pink sound tools. Audio objects generate, process, or consume audio 
data. All audio objects are descendants of the C++ class, MAudio. An audio object can have N audio 
input ports and M audio output ports. 


N audio input ports M audio output ports 


N20 M20 


MAudio 


Audio objects can be connected together by connecting their ports. This is analogous to using patchcords 
to connect audio components together in the real words In the illustration below, an audio object, 
TSimpleSound, is connected:te.a:speaker, [Speak 


Audio objects are co 
functions for playin 
Play() is called, aud 
heard on the compu } 
plays whatever audio data i is pumpe 
sets the volume for whatever data plays: 


Generally, audio objects are implemented cort 
object to represent a physical piece of hardwa 3 

computer. In this way, external audio devices i 3 in be 
represented as audio. objects. 


TSimpleSound TTelephoneSet 


TSimpleSound 


TSimpleSound both records and plays voice 
annotations. The telephone handset is used 
for input and output. 


One sound plays the greeting. The other 
records a message. 
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Music Synthesis 


TSampler TReverd — tSpeaker 


Reverb is added to a sampling synthesizer be- 
fore it is played through the speaker. 


Multi media soundtrack | Remote Voice Access 


TTelephoneLine 


Audio objects a a wide variety of 

uch as playing a sound - wit! 
objects and connect the he Pink Sound Tools provides “conve Idio 
functions that are need One such object, TSampledSound, is a sing] useful for recording 
and playing sound. TSampledSound conceptually contains a TMicrophone, a TSimpleSound, and a 
TSpeaker. 


[} + ir—p 


TSampledSound 
Playing a sound then becomes as simple as: 
TSampledSound beep (“/Sounds/Beep”) ; // Instantiate a beep sound. 
beep.Play (); // Tell it to play. 
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Connecting Audio Objects 


Audio objects are connected together by connecting one of the output ports of one audio object to an 
input port of another. 


The connection is unidirectional. In the above illustration, audio flows from audio object A to audio ob- 
ject B. Audio object A is said to be the producer, while audio object B is the consumer. 


Audio Ports 


iF: are named 
rts and a list of audio 


The C++ class TAudioP¢ 
using either strings or to: 
output ports. 


© ports. Both Input and 
bject has a list of audi: 


The TAudioPort:: ConnectTo () member ft 
input port of the other. 


TSimpleSound 
TSpeaker 


put”) .Co tTo (b.GetInpu 


The MAudio::Get@u udio object’s output port I 
It returns a TAudioPort if a mate nd, otherwise it generates an ex 
does the same for an audio object’ s input port list. Both of these functions are ‘overloaded to accept 


TToken objects also. 


TAudioPort::Disconnect() is used to disconnect ports. 
Audio Types 


Each audio port has an audio type associated with it. The C++ class TAudioType i is used to represent 
audio types. Audio type specifies what the format of the audio data is. An audio type consist of three 
fields, data format, sample width, and sample rate. 


Data format specifies the type of samples - offset binary, linear, or floating point. Sample width deter- 
mines how many bits are in each sample. Sample rate measures the number of samples per second. 
Typical audio types are listed below: 
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Audio Type 
Data format | Sample Width | Sample Rate Description 
(bits) (samples/sec) | — 
16 44,100 Used by CD players, 
integer DSPs. 
| 48000 Native to RISC, 


When an audio output port is connected to an audio input port, the audio types must match. Ot 
an exception will be generated... This. requires. that.converters be available to convert between.the: 
formats and sample rates. audio objects. The Pink Sound.#6 
a general purpose conve onvert from one audio datas 
TConverter has one inpt 
to indicate what type wi 
when the ConnectTo() 


ssed parameters 


t way, the type of the: S ports is known 


Conversions between: 
The number of diffe 
conversions do not q 


pes, especially between different sample ré 
udio. types used on a single computer 
eal time. f 


<omputationally expensive. 
minimized so that type 


New data formats itt F eve 
The TAudioPort::@ 


question. For example, if a connect: ware 
on the computer, then the call will signa : 


Audio Pla ers 


sizers, 
speech synthesizet ‘a mixin class 


defined for it - MAudi 


Defining an abstract base class for audio players has the benefit of making it possible to play any object 
polymorphically, as long as it descends from MAudioPlayer. For example, it is possible play each sound 
in a list of pointers to MAudioPlayers without caring if the sound is a sampled sound, synthesized musi- 
cal note, sound effect, or segment of synthesized speech. 


The most important member functions of MAudioPlayer are Play(), which starts playback, and Stop(), 
which stops playback. GetPosition () returns a TTime containing the current play pointer into the sound. 
This is analogous to the value of the tape counter ona tape recorder. GetPosition can be called after 
Stop() to determine where playback stopped. Another function, SetPlayRange(), takes two TTime objects 
as parameters. It restricts playback to the range in the sound between the two TTime objects. These four 
functions - Play(), Stop(), GetPosition(), and SetPlayRange() - can be used to implement the familiar tape 
recorder-style functions - play, stop, pause, resume, skip, fast forward, and rewind - as well as more ad- 
vanced features needed in sound editors such as playing a highlighted segment. 


Another member function is PlayPrepare(), which performs time consuming playback initialization, such 
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as paging in the first few seconds of a sound off of the disk. Calling PlayPrepare() before Play() guaran- 
tees that when Play() is eventually called, playback will commence with minimal latency. 


Wait() causes a process to block until playback is finished. GetClock{) returns a TClock that is synchro- 
nized to the sound’s playback. This clock’s offset is zero when the sound starts playing. The clock ad- 
vances at the same rate as sound playback. This clock can be used for synchronizing events to playback 
of the sound. 


Time Units 


It is often necessary to indicate a position in a stream of audio. For example, GetPosition() has to refurn 
the value of the playback pointer. TTime objects are used to represent time in all parameters and return 
values in the Pink Sound Tools. TTime is subclassed into various time units, such as seconds and milli- 
seconds. For programmers who would rather think in terms of sound samples instead of some other 
time unit, a subclass of TTime, TsoundSamples, is defined. TSoundSamples requires two parameters in 
it’s constructor, a sample of ese two together can be used to conve 
TSoundSamples object to ubclass. 


Relative Playback 


Often it is desirable to p a musical chord, for 


two objects simultaneously. When playing: 
example, all notes shou 


e started at once. 


ting digitized phrases to- 


At other times one we 
lessa our inbasket”, 
,. dae 


gether for voice mail: 
one might play “Yo 


Both of these cases‘ 


On at 


time 


time time 


Play me Otime units after s starts. 


Play me O time units after s finishes. Play me 7 time units after s starts. 


MAudioPlayer defines a member function, PlayWhenQ, to handle this: 
enum RelativeTo { kStart, kEnd }; 


PlayWhen (MAudioPlayer& s, TTime t, RelativeTo startOrFinish) ; 


Audio Player/Recorders 


An audio player/recorder is an audio player which can also record audio. The C++ class 
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MAudioPlayerRecorder represents an audio player/recorder. It descends from MAudioPlayer. 
TSimpleSound, which plays and records sound files, is an example of an MAudioPlayerRecorder. 
MAudioPlayerRecorder has a Record() method to initiate recording. Recording normally starts at the be- 
ginning of the sound. SetRecordRange can be used to selectively record into a portion of the sound. 
RecordPrepare() performs time consuming preparation prior to recording, if any. 


Recording normally causes audio to be inserted into the existing sound. ReplaceWhenRecording () can be 
called to cause audio data to be recorded over instead of inserted. Audio player/recorders that support 
multiple channels of sound will often use the replace feature, as sound needs to be recorded into one 
channel while maintaining synchrony with the other channels. InsertWhenRecording() ) resets recording 
back to inserting instead of replacing. : 


System Objects 


System objects are used to 
TSystemSpeaker and TSys 
puts. Each has a gain cont 
Doing this would cause « 
direct audio within TSy: 
output instead of the c 


such as the computer's speaker and 

hat represent the computer's audi 
st processors, such a TReverb;: 
computer to be reverber. 
ne so that a telephoné 
uter speaker and microphone. 


ystemSpeaker. 
So possible to re- 


Control-panel type applications can use these objects to implemen 


A parenthetical note al 


application would. 
twiddle. Another’ ee 
volume. These keyboard commands 
would have to be intercepted by the systet bei ion. ‘ould 
be provide a graphical volume control that's isi c 
control will have to be investigated further. 


Future Directions 


There are anu 


‘es that will be add: 
These are part 5 . 


and are 


o audio objects: 
sed in the following: 


Degradation 


When there isn’t enough CPU time to process all of the audio objects on a system, we need to degrade 
gracefully. There are a number of schemes for doing this. Each will be discussed here. 


Least Recently Used Algorithm 


A method used in music synthesizers is to stop playing the oldest note when there are more notes than 
the system can handle. This works well because the oldest note has usually decayed the most in ampli- 
tude and can be dropped without notice. 


In Pink, we could drop the oldest sound when we run out of CPU time. A “sound” in our case would be 


a playing audio player. Precedence would have to be given to audio player/recorders which are record- 
ing, as interrupting recording is generally more offensive than interrupting playback. 


Priorities 
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With this scheme, each audio object has a member function to set and get a priority. Priorities are floating 
point values that range from 0 (lowest priority) to 1.0 (highest priority). When the system runs out of 
real-time, it will drop objects with lower priorities until real-time is reestablished. All objects at the same 
priority are dropped at once, so the developer can group objects together that should be dropped togeth- 
er. As real time becomes available, audio objects are added back in in reverse order. 


One problem with this scheme is determining what to do with dangling audio inputs and outputs to ob- 
jects as they are dropped. One solution is to only attach priorities only audio producers, such as audio 
players and microphone objects. As these objects are dropped, all objects that they feed would be 
dropped too, unless they were still being fed by some other object. 


In the above example 
lowest priority. Cis 
on A. If there was no 


Delayed Playt 


(dio objects B and C would be dropped firs 
ed because it depends entirely on B. D 
time:left,. A and D would be dropped a 


ped because it has the 
id because it still depends 


Another degradation: that could 

Playing a sound to tell the 1 could be del al sec- 

onds or so without causing harm. d by giving ¢ player 
t 


a SetTolerableDelay() call that would sp be tolerate 


would be zero tolerable delay. 


be to add degradatit this 
toffeal time, can tell object f but still 
‘An eight voice polyphonic’ Si iple, could de- 


Non Real-Time Operation 


Normally, audio objects are run in real-time or, if the system doesn’t have enough CPU time, they are 
dropped. Sometimes it is desirable to run objects in non-real-time. An example would be non-real-time 
signal processing, where complicated sounds are synthesized and stored on disk instead of played 
through a speaker. Member functions can be added to MAudio to set and clear a real time flag. When in 
non-real time mode, the object is executed at a low priority in the background. It is never dropped. 


Smart Connections 
A future enhancement would be to add a new function, TAudioPort::SmartConnect(), which will auto- 


matically insert a converter for the caller if the audio data types don’t match. This form of weak type- 
checking could make programming easier, but it hides computationally expensive converters from the 
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programmer, which may not be ideal for programmers interested in predicting real-time response. 


Audio Groups 


Sometimes it is desirable to create audio objects that are composed of other audio objects. In the illustra- 
tion below, a new instance of an audio object, anAveryFisherHall, has been created using instances of 
TReverb and TEqualizer. 


alTReverb 


aTEqualizer 


anAveryFisherHall is an 
TAveryFisherHall. Au 
MAudio. 


of TReverb and TEqualiz 
ry the C++ class TAudio: 


iponents of 
ch descends from 


-omponent MAudios are 
nd the ports are connected 


An audio group has a 
added to the group’s; 
together. 


‘of component MAudios. To create an audi 
ponent list, new input and output ports ai 


Control of compon 
Play Groups 


Often it is desirable to create a new; 
combine eight sounds, each representing: 
want to combine the sounds “You have”, 


A play group is a group of audio objects contai | . > sented 
by the C++ class TAudioPlayGroup, is both a ; : both 
TAudioGroup an 


Using TAudioPlayGrour d € 
times of these sounds can be by their respective PlayWhen() fun 
method can then be called to fire off the whole shebang. 


rh p y group’s Play() 


Writing New Audio Objects 


It is expected that most users of the Pink Sound Tools will use existing audio objects, and not create their 
own. Creating new audio objects involves a specialized knowledge of sound and signal processing. This 
section is for those readers who would like to create their own audio objects. 


- Processing Audio 


Connections between audio objects are implemented using buffers of audio data. Each connection, or 
“patchcord” has a buffer associated with it. Every audio object has a Run() member function which 
reads data from its input buffers, processes it, and writes the result to its output buffers. The size of the 
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buffers is variable but small, from 1 to 1000 milliseconds worth of data. This amount of time is called a 
frame. 


input buffer(s) output buffer(s) 


one frame . 
of audio 


An audio object is either active or inactive. Active objects are producing or processing sound. Inactive ob- 
jects are silent. A sound file player, for example, is inactive until it is told to play, at which point it be- 
comes active. It remains acti which point it becomes inactive again... 


Within each team there i 
team. The order of the li 
(producers must run bef 
task steps through the 
must run in real-time, | 


ween the objects 

ie sound processing 
calling the Rung) function of each active obj 
eit runs at a high priority. 


A sound server team t 
audio together, and p 
heard simultaneou 
in from the comput 
objects in them. Th 


Application Team 


Sound Processing 
Task 


messages 


audio data to 
speaker 


The sound server has internal buffers for input and output audio. These buffers are shared so that they 
can be accessed by the sound processing task. The output buffers are used for playback. They are filled 
by the sound processing tasks and emptied by the hardware. The sound server sends a message to the 
sound processing tasks requesting more data when the output buffers are nearing empty. Recording 
works in reverse. The sound server sends a message to the sound processing tasks requesting that they 
consume more data when the input buffers are nearing full. 


Interface for Writing Audio Objects 


MAudio has public and protected member functions which are used specifically for processing sound. 
These member functions are only used by those who wish to modify existing or write new audio objects. 
The member functions are divided into two categories, 1) signal processing and 2) activating and deacti- 
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vating. 
Signal Processing 


The Run() member function performs the actual signal processing. For a sound file player, that means 
getting audio from the sound file and writing it to the output buffer. For a reverberator it means taking 
samples from the input buffer, processing them to add reverb, and writing the result to the output buffer. 
Run() is almost always overridden when writing a new audio object. Because it is processing anywhere 
from 22,254 to 48,000 samples a second, Run() should be coded to execute as efficiently as possible. Run() 
can call protected member functions GetInputBuffers() and GetOutputBuffers() to get its input and out- 
put buffer lists, respectively. 


A RunPrepare() member function can be overridden to perform time consuming preparation prior the 
Run(). Typically this is used for caching pointers to input and output buffers so Run() doesn’t always 
have to spend time figuring out where its buffers are. RunPrepare() is called much less frequently than 
RunQ) - it is only called when an object first becomes active and whenever the number of it’s in utand 
output buffers change. 


Objects that implement s 
cessed data to the sound: 
ber function InputAud 


sd member function Outpy ; 
se, microphone ep r 
sound server. 


to hand pro- 
e protected mem- 


Activating and 


Most audio objects n s care of this for 


ae for ee 


Deactivate () is called when an object is deac 
override this function. 


‘AudioPlayer and would not have to worry abou ae 
ActivateMe() directly. 


Protected member function DeactivateMe() is called when a server object wants to deactivate. For exam- 
ple, a MAudioPlayer would call this when it has finished playing a sound. 


Hardware Independence 


Hardware independence is achieved by providing new implementations of existing audio objects. Often, 
it is desirable to extend an object as well as create a new implementation. Extension is accomplished by 
subclassing audio objects. Let’s illustrate this with an example. 


There are many different types of telephone systems in use today - analog, Integrated Digital Services 


Network (ISDN), and private branch exchanges (PBXs) such as Rolm, Northern Telecom, AT&T, and 
InteCom. None of these systems are hardware compatible with each other, so all will require different 
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hardware interfaces to our personal computers. 


Our goal is to provide.a stable, standard programmer interface for dealing with telephones - regardless of 
the particular telephone system. We do this by defining an object that is an abstraction for the phone sys- 
tem, TTelephoneLine. We define member functions common to all phone systems, such as a means to 
make a call and answer the phone. 


Now, let’s say a developer wants to create an object for a particular phone system, lets say ISDN. The de- 
veloper creates a subclass of TTelephoneLine, say TISDNLine. The developer overrides the functions de- 
fined in TTelephoneLine so that the implementation uses the ISDN hardware. Existing telephone appli- 
cations defined using TTelephoneLine will work with the new TISDNLine object. a 


abstract base class 


TTelephoneLine 


The developer can a 


can choose 
to take advantage o, 


, 


The subclasses are d ¥ Splicati on’t 
have to be recompiled to use a new ini i : 


Class Hierarchy 


Note: All objects descend from MCollectible. 


MAudioPlayer 


MAudioPlayerRecorder 


TAudioGroup 


TAudioPlayGroup 
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TAudioPort 


TAudioType 


TSoundSamples 
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Introduction 


An important feature of the audio objects are that they provide a stable, standard application program- 
mer interface for audio, speech, telephony, and music applications. The Pink Sound Tools define a set 
audio objects to do the most common sound and speech operations. The definition of the public member 
functions of these classes is the application programmer interface. This section describes those classes. 


Audio 


This section describes classes for playing, recording, and processing sounds. Unless otherwise noted, all 
of these objects descend directly from MAudio. 


straction for a 
o connections 
tputs. It descends 
Record() methods as 
PlayWhen() for relative 
tClock () for getting a 
layback and recording. It 
ns for editting the sound 
ut volume. 


ying and recording sound: 
nd TMicrophone built.i 
ary. It has no inputs, 


TSampledSound 


er 

ll as SetPlayRange() for playing segments @ 

aying, Wait() for waiting for playback t 

yents and alarms can be syn 

Insert(), Copy( and Repl 
() 


TSampledSound 
s.Play (); 


one or two in- 


ud stances of TSpeaker ca can exist, either in one task or in different tasks and teams. 


The output of each TSpeaker is summed and played out on the system speaker. 
TSpeaker 


TMicrophone 


phones (a la Elsie) or external microphones (Farallon Macrecorder) can be accom- 


TMicrophone records audio from a microphone or line input. Both built-in micro- 
i modated. TMicrophone has one output. 


TMicrophone 
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_TSimpleSound 


TSimpleSound is identical to TSampledSound except that it does not have a built 
in speaker and microphone. Instead, it has one output and one input which can 
be connected to any other audio object. 
TSimpleSound 


TConverter ; 
TConverter converts its input to another audio type and outputs the same audio 
data but ina different format. It has one input and one output. The constructor 
for TConverter is passed parameters to specify what conversion should take place. 
TConverter 
+- ixer is a very basic mixer that will sum£ nputs into a single output. 
np mixers that sum to ster e gain and panning on 
nstructed from TMixer orhardcoded lat 
TMixer 
TGain can increas sin- 
gle output. Large sigs 
TGain 
TSplitter 
| nd splits it into 
TSplitter 
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Audio Processing 


TReverb 

TReverb causes its input to sound like it is ina large room or hall. It addsa 
lia. | hi pleasing effect to music and sound effects. TReverb has one input and one out- 

put. It has a SetMix() function to determine the ratio of processed to unproc- 
TReverb essed sound. It has a SetRoomSize() function to set the size of the room being 

emulated. 

TEqualizer 


ttenuates various frequencies in. 
e audio output. It has fune 
dS. 3 


iD egnal. It 
t the levels of 


TEqualizer 


TAutomaticGainControl 


icGainControl implements 
tutput. It is used to ke 
mtrol is especiall 


gain control. It has one 


TAutoGainContr 
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Class Hierarchy 


MAudioPlayer 
MAudioPlayerRecorder ; 


TSimpleSound 


TMicrophone 


inControl 
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Speech 


This section describes classes for speech processing. 


Text-to-Speech Synthesis 


A Text-to-Speech synthesizer converts text into speech. There are a variety of classes associated with this 
process, the simplest being TTextToSpeechSynthesizer. 


TTextToSpeechSynthesizer 


TText ToSpeech- 
Synthesizer 


tied words have been 
ictionaries to help it 


going to speak. It can send events to a task; 
spoken. It can use application specific pr 
ly pronounce words. 


Converting T 


For programmers who want mo; 
There are three distinct phases in the: 
es, and sentences. The first phase involves 
ating an unambiguous representation of the: 
stream of text. Conversion of text to phoneme 
built-in dictionary of exceptions to these rules, 
custom dictionaries embodying pronunciation 
cific application 


The second ph 
representation w 
be realized in contex 
quired phonemes, or allophones,: 
item. 


al text are to 
ants of the re- 
uration of each 


The final step consists of accessing pre-stored digital data corresponding to each pair of allophones, mod- 
ifying their pitch and duration in accordance with the control parameters included in the allophone 
stream, concatenating the resulting sound segments into a buffer of continuous audio data, and playing 
the buffer as a sampled sound. 


Pink Sound Tools will support the use of multiple synthetic voices. These voices will differ in such fea- 
tures as speaking rate, speaking style, baseline pitch, and pitch range, as well as in the language each 
voice is designed to speak and the actual digital data used to play out allophones. 


The following diagram illustrates the relationships between these different elements. 


a TEIIIS IEEE IEEE SEEEEEEEENEEEEN 
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Exception 
Dictionaries 


Phonemes 


Phoneme-to- 
Alloshone 
erter 


Text-to-Phoneme 
Converter = 


Allophones Saad 


Allophone Play 


ice Definition 


The classes described below provide altern 
phase of processing. Each class is used interna 


TTextToPhonemeConverter 


from 


is.an abstraction : 
i nverted to 


t.. dehasa SetInput() function wi 
phonemes. It has tVerboseOutput() produces a! t redundant 
phoneme specificat Output() produces a compact, coded representatios A le for efficient 
storage. The class also has functions which set the characteristics of the synthesized voice which affect 
application of the text-to-phoneme conversion rules, and functions which permit addition and deletion of 
customized pronunciation dictionaries to augment the built-in exception dictionary. 
TTextToPhonemeConverter might be used to facilitate the process of creating a new custom dictionary, 
since it could be invoked to produce a first-pass transcription of problematic words which would then be 
edited and corrected. 


TPhonemeToAllophoneConverter 


TPhonemeToAllophoneConverter is an abstraction for the second phase in the process of generating 
speech from arbitrary text. It is not an audio object. It has a SetInput() function which takes in pho- 
nemes to be converted to allophones. It has two output functions: GetVerboseOutput() produces a hu- 
man-readable but redundant allophone specification; GetTerseOutput() produces a compact, coded rep- 
resentation suitable for efficient storage. The class also has functions which set the characteristics of the 
synthesized voice which affect application of the phoneme-to-allophone conversion rules. 
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TAllophoneToSpeechS ynthesizer 


ToAllophoneToSpeechSynthesizer is an abstraction for the final phase in the process of generating speech 
from arbitrary text. It inherits from MAudioPlayer. It has one audio output. It has a SetInput() function 
which takes in allophones and their associated control parameters. When Play() is called, these allo- 
phones are spoken. The class also has functions which identify the data tables from which segments are 
to be extracted for concatenation and which specify other global voice characteristics which affect the syn- 
thesis process. 


TPhonemeToSpeechSynthesizer 


TPhonemeToSpeechSynthesizer is an abstraction which subsumes the second and third phases in the pro- 
cess of generating speech from arbitrary text. It inherits from MAudioPlayer. It has one audio output. It 
has a SetInput() function which takes in phonemes to be converted to speech. When Play() is called, these 
phonemes are spoken. The class also has functions which specify global voice characteristics which af- 
fect application of the phor -to-allophone:< ion rules and the process of playing out-allophe 
TPhonemeToSpeechConv id the overhead of text-to-ph x ‘ersion when 
large amounts of phonemii raight text are to be synthesi 


TVoiceDefinitio 


TVoiceDefinition is a ¢f 
of the voice to be syn 
called at each stage in 
permit modificatio 
spoken per minute. 
voice. SetPitchRan; i nental fre- 
quency of the voice: : 
precision to be requested. SetPau 
phrases and sentences without othe 
defines the rule sets to be used in generatifi 
significantly from language to language.) F 
ments to be used during the final stage of pro 


s which contains a variety of information 
ized. It is not an audio object. Various 


Ye specific characteristics 
tions of the class are 

tion has functions which 

f words to be 


TSpeechRecognizer phrases have been recognized. There are likely to be many subclasses of 


a stable interface for applications that use speech recognition. 


et ST a a aS a a 
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Speech Recording and Playback 


TVoiceCoder 

TVoiceCoder is a descendant of TSimpleSound. It has one input and one out- 
put. It overrides Record() so that when recording, it removes silence from the 

audio signal, thus saving disk space if you know the signal will only contain 
k~—a voice. It can change the rate of playback without changing pitch. It can store 
TVoiceCoder the voice in a highly compressed form suitable only for speech. This object is 


useful for phone answering and voice mail applications. 


TPhonemeToSpeechSynthesizer 
TSpeechRecognizer 
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Telephony 


This section describes classes for building telephone-based applications. Unless otherwise noted, all of 
these objects descend directly from MAudio. 


TTelephoneSet 
ar TTelephoneSet represents a local telephone attached to the computer. It can 
jy be recorded from and played to. Many instances of it can exist. It can send 

Beni events to a task when the handset goes on and off hook and when buttons are 
“fea resse 


TTelephoneSet 


TTelephoneLine 


n the central office or 
ne line, but not the data 
ISDN). Data communi- 


’ TTelephoneLine represents the phone line. 
* PBX. It is an abstraction for the voice feat. 
nications features (such as those : 


Ooo TDTMFDecoder is only 
ooo known as Touch T: : i : izes a 
ood 
OOO ouch tone, it posts 
TDTMFDecod : 
; TToneGenerator generates Dual Tone Multi Frequency tones(DTMF, com- 
\X\ monly known as Touch Tones). It descends from MAudioPlayer. It has one 
d audio output. 
TDTMFGenerator 
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TModem 


TModem 


TModem converts audio data into digital data. It has one audio input and one 
audio output. It has functions for setting equalization, call progress monitor- 
ing, and configuration. TModem must be designed in conjunction with net- 
working to see how it fits into their world. 


Class Hierarchy 


TDTMFGenerator 


TTelephoneSet 
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Music 


This section describes classes that can be used for music synthesis. Of course, all of the objects found in 
the Audio chapter can be used for musical purposes too. 


TSampler “ 

TSampler is a descendant of TSimpleSound and inherits all of its functions. It has 

new features that make it useful for music, however. It has one (mono) or two 
LLIRLLS (stereo) outputs and one or two inputs. It can play sounds at an arbitrary pitch. 


TSampler 


a a ee 
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Editors 


The Pink Sound Tools will provide editors for editing sounds and graphically connecting audio objects. 
All of these editors are built from objects that any application can create and use directly. The editors 
serve two purposes, 1) to give developers tools to create sounds and connections of audio objects for use 
in their programs, and 2) to provide a standard interface for end users for doing the same. 


Sound Editor 


A sound editor gives developers a means to create and edit sounds played by the audio object classes. It 
also provides a standard user interface for creating and editing sounds for voice annotation, voice mail, 
sounds for presentations, and the like. 


The simplest way to record and pl 
the controls on a standard £@ 


S 


ehave in a manner consis- 
own the play and record 
Sbject that implements the 

1 tand file, reading 


It has buttons for rewit 
tent with a physical t 
buttons at the same t 
sound palette. TSoui 
in a new sound, an 


A subset of the sou’ € 
the following example, a “st 
ette subset. 


When the fast forward and rewind buttons are eliminated, the play button always plays from the begin- 
ning of the sound, and the record button deletes the existing sound and makes a fresh recording. 


TSoundEdit is a C++ object which displays a visual representation of the sound. This object would al- 
ways be used in conjunction with a TSoundPalette object to give the user visual control over editing the 
sound. Functions are provided to follow the mouse for dragging and selecting, query the view for the se- 
lection bounds, change the size of the view, scroll, and zoom in and out. Applications are encouraged to 
use TSoundEdit and TSoundPalette together if they require precision editing of the sound. We will pro- 
vide a sound editor application, based upon TSoundEdit and TSoundPalette, which developers and users 
alike can use to create and edit sounds. The editor, ina prototype Pink window, is shown in this illus- 
tration: ; 
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<</ miel>[>>| (0:28 fe 


It is expected that third 
of TSoundEdit and TSo# 


Audio Object Editor 


Connecting audio 
lined the C++ synt 
developers to crea: 
associated with ité 
rubber-banding lin 
double clicking on them. This woul 
might in the future use a visual digital sigh 


the audio 


a ee 
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Sound Effects Library 


Sounds are difficult to create from scratch. It takes a great deal of experience, knowledge, and patience 
to record or synthesize sounds. Recording sounds from movies, television, and even sound effects 
records can violate U.S. and international copyright laws. 


We want all developers, most of whom are unfamiliar with sound, to be able to add sound feedback to 
their programs. End users will want sounds to use in sound track presentations or dramatic voice mes- 
sages. The Pink Sound Tools will include a sound effects library to be used by both developers and end 
users. The sounds can be used in conjunction with the Pink Sound Tools without violating any copyright 
laws. 


The size of the library need not be large. Anywhere from 50 to 200 sounds should be sufficient. The 
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This ERS'6 
used for thé 
Dink. The colle 


he text classes in this document do not 
support rendering or measuring text; they 
are for manipulating text in memory only. 
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Introduction 


The classes described in this document manipulate 
character and style data, and are the basis for the text 
ayout classes (please refer to the ZZText ERS). The 
classes described in this paper represent the lowest 
evel string manipulation available under Pink, replac- 
ng functionality such as strlen and strcat. Even the 
concept of “length” is maintained in an implementa- 
ion-specific manner (length, for example, is defined to 
se the number of characters, or sixteen bit entities in 
‘he string, not the number of bytes). . 

Note that the root of the text hierarchy, 
TBaseText, has no fields and a protected constructor. 
The TText class implements the protocol defined in 
TBaseText. For the purpose of 
character data, an abstract cla 
fined, supporting insertion ané 
rom a stream of text, as we 
and substrings. At present th 
of this base storage class: F 
implements an pointer to 
compressed), and TFancy 
ments character storage as: 
ficient insertions and dele: 

In addition to the § 
style-related classes: TS. 
TStyle implements a ni 
style, such as “italic.” A style set is a a collects 
that apply to a run of text. Each node in a styl 
style set and a count (maintained in the run 
structures) of the number of characters across wh 
the particular style set applies. The classes MStyleR 
and TText are combin produce the lower-co 
mon denominator for’ and maintaining sty. 
text. The resulting rh: 


eapTextStorage, which 
lock of data (possibly 


without all of the obvious cost. Qne-f 
classes (eventually) will be compression into fewer bits, 
probably eight, whenever possible. Note that this is 
not currently implemented. It is worthwhile to note 
that if the text being represented is a random collec- 
tion of characters with no common language, script, or 
other restricting attribute that the overhead for this is 
a one-node mun array that identifies the run as sixteen- 
bit data. A goal of the implementation is to minimize 
the storage required regardless of the composition of 
the text being stored, while also minimizing access 
times to textual elements (e.g., characters, substrings, 
styles, etc.). 

For more information about higher-level facilities, 
please refer to the Line Layour Manager ERS and the 
ZZText ERS. 


Theory Of Operation 


The base text classes implement styled and un- 
styled text in a way that attempts to choose a storage 
scheme that is appropriate for the manner in which the . 
text is being used. The decision about which scheme is 
appropriate is made dynamically, and may change 
many times during the life of a text object. 

Two classes of particular interest within the base 
text hierarchy are TTextand TStyledText. TText and its 
descendants, such as TStyledText, toggle between 
using an array of (currently uncompressed) sixteen-bit 
characters and a recursive run array of arrays of sixteen- 
bit characters, depending on the length of the string. 
For strings less than a certtain number of bytes long, 
“flat” string structure is used. When 
s the maximum flat structure size. 
‘runs” of data thre-quart 
f bytes per flat structu: 


tened” out. 
is to prevent: 


InsertAt and DeleteAr methods): The only extra pain 
the client programmer must incur is be to make sure 
these insertion and deletion methods are called from 
the newly derived class. 

Another goal is to support an unbounded set of 
styles, including user-defined styles. This will (hopeful- 
ly) allow someone to create a special effect in some 
program such as LetraStudio and name the result, and 
then export the entire style specification to other pro- 
grams. This would allow text not actually entered (i.c., 
typed in) within the scope of the program directly sup- 
porting the “special effects” to nonetheless make use 
of them, even for newly entered text. The style scheme 
is open: styles define their data. Only style names are 
implemented in the base protocol. 
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TsBaseText 


TBaseText is an abstract base class from which all 
of the text storage management classes are derived. It 
has no fields and its constructors are protected. 

At present, this class supports the minimal text 
manipulation set of functions. It is our belief that any 
other functionality, such as string concatenation, can 
be achieved through a trivial combination of the meth- 
ods provided. Please see the Open Questions section at 
the end of this document. 


TText 


TText is the general- purpose text class. It may be 
thought of as a dynamic array ©: 
though the internal representa 
ies depending on the amount: 
of usage. Text may or may n 
compression decision will 
one that weighs the cost G 
cost of straight sixteen-bit 
point at which the data r 
one contiguous block to: 

be determined by this cl 


f compression against the 
poding, In addition, the 


TTextSelection 


This class implements a subrange of text. 
methods take an argument of class TTextSelection 
insertion point in the formatting classes is implemet 
ed asa TTextSelectton with length is zero. 


or 


for text. The name may fee be text object or a 
token. In the case of a text object, the name is first to- 
kenized and then stored in the name field. As an exam- 
ple, consider a style named “bold.” Somewhere on the 
system there will likely be a clearing house for standard 
styles names (and other items), so the token for bold 
should be well-known (this is under investigation). 

N. B. The method JsEqual is provided, and re- 
turns true if the style names match. It is the reponsibil- 
ity of the client to implement IsSame to do the right 
thing if two styles are equal. 
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TStyleSet 


This class implements a named, expandable set of 
“styles” for a given run of text. In this context, even 
font changes are considered “styles.” A client specifies _ 
a style as a TStyle object and may add or remove it 
from the set of styles managed by this class. Query 
methods are also provided to determine the contents 
of a style set. 

Note that style sets are reference counted. Style 
sets are often transient entities in style runs, and to 
protect them from being deleted automatically by 
methods in the Uulity Classes, all constructors have an 
auto increment parameter, which defaults to true 
(which means that the reference count field should be 
initialized to one). Clients that do not override the 
uito increment value and set it to false 


ally, ae sets 
ting their refer- 
Ses, and only for style 

cally as other runs are 
s that compose a style set 
tructor of the style sets that 
berate—styles may exist in 


re created without initia 


sets that are gener 
split. Note also £ 
are not deleted 


tonsist of the 


boldSoyle, 
‘cts of class 


They could 
that this does f 
the style Bold): 


TToken boldStyleName (PartialChar *) “Bold"); 
TStyle* boldStyle = new TStyle(boldsStyleName) ; 


// Ditto for the other two styles... 


MBaseRun 


This class implements basic functionality needed 
to manipulate runs of information. It has one field of 
class TRunArray and provides methods to find the 
previous run, the next run, and the length of a run 
from an index. It also has two methods, DolInsertBefore 
and DoDeleteAr that are called to keep the runs in 
synch with other data. 
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MStyleikans 


This class implements runs of style sets. Each node 
in the run array is of class TStyleSet, the expandable 
style set from above. This class manages the mainte- 
nance of runs of style sets as text is added to or re- 
moved from the text with which a style run Is associat- 
ed (it is normally used as in TSzyledText, see below). 

The method SetStyleInRange is additive. That is, it 
performs a union of the styles in the set specified in the 
call with all style sets encountered in the range given. 
In the example below, if the run of [italic] is set in the 
middle of a long run of [bold], there will be a run of 
[bold] followed by a run of [bold, italic], followed by 
another run of [bold]. This is contrasted with another 
possible alternative: [bold] followed...by..[iralic]...fal 
lowed by [bold]. Use Replacs 
new style set ragardless of an 


TStyledText 


This class is a c 
MStyleRuns. It provides 
fined primarily for the pi 
from rolling their own 
that this class inherits i 
structors, plus two ins = 
methods. These last two routines are Ovett 
ones specified in the base TBaseText class ard 
call methods in MStyleRuns such as “DoDe 
and “DolInsertBefore.” 

Note also that the recommended approach for ‘ 
ents to use when addi dditional runs to a text ¢ 
ject would be to pr@ 
say MVoodooRun 
such as TVoodooTe 
The exact definition © 
ercise for the reader. 


_of TText and 
and is de- 


MSearchText 


This class supports basic text searching on an ob- 
ject in the TBaseText hierarchy. There are a good. 
many language-dependent features that have yet to be 
thrashed out (what does “case sensitive” mean, for ex- 
ample, and who will implement it), so only basic, 
hopefully fast, searching will be supported for now in 
this class. In addition, the careful reader will realize 
that the international group has yet to be involved in 
this; arguably a bug. 


Before SetStyleinRange (italicStyle) 


Italie ——————- 
Bold —----_--- SSS 


ea a ae eae eG TI PT RE 


After SetStyleinRange (italicStyle) 
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Examples 


Creation of text objects is accomplished as follows: 
TText* someText = new TText ((PartialChar *) “Hi there.”); 
TText someMoreText = TText((PartialChar *) “Hello world.”); 


The nth character of a string can be referenced by: 
UniChar c = someMoreText [n]; 


But note that... 
someMoreText [n] = ¢; // ...18 not supported. Use InsertText instead. 


Text from one text object may be inserted into another one: 
someText~>InsertText (someMoreText, 5, someMoreText->Length()) ; 
...which results in all of the text in someMoreText being inserted before the first “e” in “Hi there.” in 
someText, yielding: “Hi thE, es 


Data from a text object may: 


Data may be extracted frotit:a text object in any of several ways. The meth 
return. In the first exa ialChar* data is returned (essentially 
PartialChar* part ‘Ghar *) malloc(100) ; 
someText->Extra partialChars) 
In the next example 
UniChar* uniChag, 
someText->Extract Text té 
In the last example, a full text objec 
TText testText; 


someText->ExtractText (0, someText ->Lengtt 


nly in the type of data they 
ir): 


The assignment operator is overloaded, so that the ving consti 
testText = 


*so 


Styled text is man st as unstyled text fa $ are cre- 
ated as in the fol 
TPointSizeStyI 


: tSizeSvyle 1s defined in “SystemSryi 
TStyleSet* ssl = 


To actually fill up a style set with styles, the client must call AddSryleToSet for each style to be included. 


ss->AddStyleToSet (pst) ; 
TStyledText* text = new TStyledText ((PartialChar *) "Sample Text") ; 


Selections simply maintain a pair of indices, and are used frequently to specify the extent over which a change 
such as a style run is to be applied. 


TTextSelection aRange({0, 3); 
text->SetStyleInRange(ss, aRange) ; 
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Open Questions 


° What types of operator overloading do users wish to see? We believe that assignment and indexing 
would be useful, and are included in this specification. Are there some others (concatenation, auto-in- - 
crement, etc.)? 


e What should I do about discontiguous selections? 


° What should we do about comparisons? There are “degrees of matchingness” specified in the 
International Specification; how are we going to integrate this into the text stuff? Do we define be- 
havior that includes some matching on the clients of a TBaseText object, or do we handle just text 
comparisons? 
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Introduction 


This document is the ERS for ZZText, the text 
formatting system for Pink. In its final form, this 
ERS will represent the services available to clients 
wishing to support text manipulation. ZZText 
embodies sophisticated text handling features cur- 
rently available on the most expensive and powerful 
publishing-oriented systems. In addition, ZZText 
provides a simple interface for basic on-screen text 
entry, facilitating dialogue box input, etc. This doc- 
ument will of contain a precise description of the 
methods in the various classes that ZZText 
comprises; that information is part of the header 
files for the text classes. 

A successful implementation 
includes enough functionality::to:s: 
demanding traditional publi 
penalizing simpler textu 
HyperCard. ZZ Text is an. 
management system built 
classes (see the Base 
support dynamic arrays: 
addition, ZZText mak 
es provided by the lin 

The distinction 
layout classes is im 
line layout services 
width of text between 
light regions, caret positions, as Swell as 
international services including contexttia 
forms, reordering (for languages such as Ar 
and mixed-direction text. ZZText provides m 
nism by which lines may be generated and arran; 
On a page; it is no 
tion level, whi 
classes. Note th 
es are clients of th 


main of the line layo 


Philosophy 


ZZText controls the appearance of text, 
specifically the layout of text (on a page, for exam- 
ple). One aspect of ZZText that permeates this en- 
tire document is a particular philosophy concerning 
text formatting: fast formatting results in poor 
quality, and good quality formatting is not fast. 
However, a good text processor supports both 
goals (fast and good). To get good text, the model 
must allow the specification of sufficient constraints 
on the text such that they satisfy the most demand- 
ing user. Less demanding users need not constrain 
the text as completely as more particular users. 

_ The belief that good and fast are, for practical 
purposes, mutually exclusive, has led to the 


_of ZZText 
setexthemselves to this approach. 


= for any given body of te2 


consideration of a two-pass approach to formatting. 
The first pass is the fast pass, and is defined as the 
pass that can keep up with a fast typist. The second 
pass is the good pass, and is defined as the pass that 
makes the Seybolds happy. The second pass consists 
of potentially more mee one actual pass through 
the text. 

The part of the second pass that is concerned 
with optimizing line breaks within a paragraph is 
based on Knuth’s TeX method for breaking para- 
graphs into lines. In addition, this algorithm is re- 
stricted to languages that have “words,” or Some 
reasonable substitute. Some languages have no 
determinable word breaks, or they are very difficult 
to define (¢., Thai), and for these cases the algo- 
rithm cannot be used. Most modern languages lend 


The Knuth method yield 


gn De ekeemely €x- 
Tr, the algorithm is 
He. Such time consum- 
implemented as unob- 

that tighten up the text 
trating on another part of 


pensive computational 
computationally 


strongly reflect 


standing of the mode ‘ZZText is based 
will aid potential clients of ZZText with respect to 
customization and utilization. ZZText is a set of 
classes that supports text editing, formatting, and 
page layout. The actual text component of a ZZ- 
Text object is represented by one of the base text 
classes, normally TStyledText. Paragraphs are struc- 
tures in a layer superimposed over the text that 
constitutes each paragraph. 

Note that all internal measurements in ZZText 
are in printer’s points and fractions thereof. There 
are 72.27 points per inch. Note also that a “units 
conversion class” is provided: TMeasure. 

The model of the text managed by ZZText is 
an extension of the classes described in the Base 
Text Classes ERS. ZZText adds to this base-level 
functionality the concepts of paragraphs, lines, for- 
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matting, views of the text, text flows, and classes to 
support pagination. 

ZZText does not implement any “user views” 
or presentations of the text. ZZText does not create 
windows, and does not directly support multiple 
views of a text object (yet). ZZText does not direct- 
ly support even a single view of text, from the user’s 
perspective. 72ZText supports TTextView objects and 
through them provides an off-screen drawing 
feature. Text view objects provide the “mold” into 
which text is “poured,” and conceptually they form 
part of the model, not a true view of the model. 
TTextView objects may be linked together to direct 
the flow of text, and may be contained within an 
object of class TPage View. 

ZZText manages “flows” of text. Such flows 


are contiguous runs of text.data..with. their atten-. 


dant style and paragraph in 
ports multiple independeg 
may “flow” into multiple 
to columns). For the pi 
such a collection of text 
Galleys are peers, linke 
to manage more than G 
list of views linked t 
defining a text flow... 
tem as a list of galle¢ 
linked list of views 
views are simply that: 
the active galley (the one where edi 
place). 

Although the term paragraph is used ext 
ly in this document, more accurate terms might 
clude block, chunk, or SroUup, as paragraphs genet 
have the most meaning in documents contain 
horizontal text. SI xt enforces no di 
tionality on te 
lar semantics for: 
grouping device, “t 
able for many uses 
TParagraphs a protocol-o only class. As an example, 
the paragraph classes could be used in an MPW- 
style editor to implement lines. 

ZZText paragraphs generally refer to a style 
sheet (a.k.a. a property sheet) to determine their 
characteristics, such as indentation, margins, default 
font family and style, etc. This separation of para- 
graphs and the properties associated with them 
makes the paragraph object a more general and 
much lighter weight object than a fully loaded para- 
graph would otherwise be. Also, it allows many 
paragraphs to share the same properties. 

To support the editing of text with respect to 
insertions and deletions such as copy and paste 
commands, the class TEditableText defines behavior 


‘referred to as a galley. 
gether allowing ZZText 
This is 5 not the same as a 


a of 
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related to such editing changes. This class supports 
multiple discontiguous selections (although such 
functionality may not be implemented in the first 
version of ZZText), tracks the insertion point, and 
cooperates in the handling of commands (yet to be 
defined). Other types of editing changes (margins, 
etc.) are supported by other aspects of the ZZText 
classes. 

ZZText provides a text manipulation environ- 
ment that supports sufficient control over the 
appearance of text that almost any desired typo- 
graphic effect can be achieved. The controls previd- 
ed by ZZText allow hanging punctuation, drop 
capital letters opening a paragraph, etc. If there is 
something that ZZText does not support, a client 
has only to add new properties and override some 
of the formatting routines. (This is certainly..a..goal. 


nality that ZZText will 
dentify “bad” lines. If, after 
1ere:remain lines that are 


TEditableGalley fe 
characteristics, paragraph style sheet 
specifying a font, style, etc., as well as certain de- 
fault behavior. The default behavior of an editable 
text object will include keystroke handling, selec- 
tion, cut, copy, paste, etc. 

A client of ZZText also should establish a view 
(which must inherit from TTextView) in which to fit 
and display the text, though ZZText will manage 
text and keep it “unformatted” if no such view is 
provided. Also, at this stage in initialization, a client 
should establish a “page view” if one is desired. 

Note that ZZText supports but does not re- 
quire views of the text. If one or more views are 
defined for the text, those views will determine how 
the text is broken, otherwise the text will remain 
unformatted. Also note that this mechanism should 


March 15, 1990 ° Dil ee ie 


not be confused with a scheme to show more than 
one view of the same text (still being designed). 

In addition, a mechanism will be provided al- 
lowing text to be broken into lines to determine its 
height, etc., without requiring that views or lines 
be instantiated. 

For ZZText to handle multiple independent 
galleys and their attendant views, ZZText introduc- 
es the concept of a Galley Manager. The purpose of 
this object is to determine which galley in a mult- 
ple-galley text arrangement (such as a newspaper or 
magazine) is the “active” one, which galleys are 
current and that need updating, etc. 


Simple editad 
boxes and simple tc ) 
possibly including text in ce 
spreadsheet, etc. 


More complex textual applications, 
including text processors and any 
uiring complex text 
iple paragraph styles, 


Typically, the classes that a client deals with de- 
pend on the level of sophistication of the applica- 
tion for which text is being used. The “dialogue 
box” case requires the creation of a single object of 
class TTextView and a single object of class 
TEditableSimpleText. For more complex applica- 
tions, a client will likely use one or more objects of 
class TTextView (possibly linked together), option- 
ally one or more objects of class TPageView, one 
object of class TEditableGalleyText per arncle or 
text flow, and one object of class TGalleyManager 
to manage multiple independent text flows (this 
one is optional if there is only one text flow, but 
recommended). 
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List of Features 


POC fb cvs teenth iataae diadoreeiomam atadeeedaeaRnes ene Probable Pass 
General Pagination 
FOIce pape Dicakcwia. sas baa ile a AO Sos ooo bce osetia ve Boeke eka an ae aan Both 
PEEVENE Page. DICdk. wc oo Wed ait ntik set Weal eae eee aw ee HO Ad See RES Both 
POrce column: break ins cat wad pears gai eate es Oa ESNet ae ee RE A ee Both 
Group objects 
Separate objects 
River detection and avoidance? - 
General Editing 
Selection Sates so aeik sabaretatd iui tule tyarnig sree aetenikle sha tas gra Mig aes hat aa nate ear a eee ene First 


we ee eee eo EE SR ee ke ee ee ee eee . First 


Pasting. .......... 3332 ee oe First 
Undo... 2... ee ok kk ee ee. First 
Font and style chang pie Ria Bbw Rb Ase we Ak Wa PRR BAS ee ee gk Ss OSs First 


Widow and orphan coiitrol... 0... ee es ee Second 
set's Aiea tee ee ee kee nde Second 
gnment (all lines) matching ? 
Vertical vastifcatig aa cde ible ue ay aes ee . Second 
Facing pages mus cae ures Second 
Columns must 1 x 
Baseline grid. . °° ee 6. PE 
Pages in a oe lee t MUSt Mths 
Lines must back up on pairs of overleaf:pages: oe... 
Column balancing................. 
Keep with next paragraph. ............ 
Footnotes ? 
Placement 
Multiple line 
Carryover to 


coe ere eo ee 


oo eee eee 


oe ee we we ewe 


ee? 


e888 RR e aa © ee ee eee 


Line layout . . 2322 ee ee EE OR ee 
Multi-direction; Both 
Device-dependen .... Both? 

Marginal notes and GUNS ar he oe eet sone cnet ener unes ate der alo Second 

Ruane headers and footers: ?: 4.0.60 ug owe bea setae ORAM ERED Bad SPS Second 
Variables. such:as pase number, date, te: p00 bea pte yre bee SHG Rela ewan ded oe Both 

Mula p Ie COMMmMNS "3.56 h ee ein toes Sh et eeaet seen eA Auer Re nee eet e-de Both 

Figures (probably a client-implemented feature)... 2... 20.0... ccc eee eee Both? 
Placement: exactly with text 
At top of page 
At bottom of page 
On a figures page 
Anywhere on a page 


Maintenance of sequence relative to mention in text 
Placement on facing pages 


TUNES CATIONS 3b oie re ectna ps a eee a CR te Hie a ea Gla ale Pe Rte 2 Both? 
See list above for figures 
‘Tables CNOrgt list) ist. bass Gn cae Gbed Sed eae cre eter eae te tes Bea ae Both 
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Equations, formulas (Not at first)... 6.6... eee cece eee eens Both 


Cross-references (Not at first)... ...----. 0 eee ee ees oat ciated consents te hg nine Maiaoel Sata Bed Second 
Bibliographical references (Not at first)... 0... 6s eee cece eee Second 
PE raCKing* ooc3 34 cesta ee eee ee te ee ee Second 
Kerning (Line layout and ZZText) *... 2.2... eee eee eee eee ees ee Te eee Tee Both* 
Margins and gutters *. 0.0.2... ete tenet teeter teers Both 

Left and right-hand pages... 2... 1. eee ce eee ee eee tees seceatete wa auaard Both 

CAROLS oes. a eck he a hie ee SES RMA ER AE ERED OS RS SEARLE RA SBS IEEE AREER AE AE Both 
Paragraph Justification * 

Lett as ec Sete neee wee e es 

Bag csdgene kes Liab bide Re ty ed hd ER ots Ais OMAR ES SSL COED EA PERE SHR EO EES 

COREE occ Wed he eS Se SMES OEE DIT SERS AAP ee ERM A 

Middle quadding*.. 2... 6... e eee eee ee ee eens 

Last line quadding options*. ... 2.2... 6-2 eee eee eee eee eee De aie te Sg We i Sta th aaa 

Justified*..... J asaresele gp. weg Maat atale ts . 

Optical alignment* (Line layout)... 2.6... 1s eee eee eee etree t ttn 


Hanging indentation*. 


Non-Knuthian last lin 
Suppress line break* 


Layout grid support 

Style Sheets *..... - 
Hierarchical?. . . .2 

Tabs * 
Right" s22ese00s 
Center) dd2 2045 saw scuse tees 
Déecimal* 4 Gane ase eer Rees 
Arbitrary character*..... Seas ys 
Various leader options*...........--+-- 


ene Ee 


@ Registered Restricted e ZZText Layout and Editing Classes e March 15, 1990 ° 24225 


Class Taxonomy 


Class Name . Description 

TStyled Text .....cecsecseeseeeseesees From the Base Text Classes, this is the class that manages the actual 
text and styles associated with a ZZText object. 

TAAJUSCCAT CHE... ecccccecessneees Implements automatic index adjustment to account for movement 
through text (due to insertions, deletions, arrow keys, etc.). 

DLV OPCTELS vo sxvovsancservietenanives Repository for information controlling the appearance of text in a 
paragraph, such as indentation, flush parameters, etc. 

6 Greener eer ere eon vere Specification class for tab stops. This class support all of the stan-  - 


dard types of tabs, and the TProperties class contains a pointer 

to an object of this class. The full definition of this class re- 

quires more discussion with the International Group. 
TChamgelnfo .......:cccccccseeeeees Class that holds change information supporting incremental up- 
dates and interruptable drawing. 


TParagraph..........-+ ing the behavior of both simple ar 
TSimpleParagraph... aph, with a reference to a Z: 
icfaults are used. Thi 
ie as ina 
ag 

TFancyParagrap Subclass of TSimpleParagraph. Thi ychavior specific to 

quality paragraph forma t 
MParagraphs. : 


TGalleyText 


tion of the new line. No run array is required for paragraph 
maintenance, but only one property sheet is allowed for all of 
the text ina TEditableSimpleText object. 

TEdttableGalleyText ............ Companion class to TGalleyText and TEditableText. This repre- 
sents the “standard” ZZText text editing object. 

TEditableFancyGalleyText....Class identical to the one above, but automatically starts a back- 
ground task to accomplish fancy formatting, including para- 
graph line break optmization. 

TGalleyManager.....ccccccccceee- Class that handles multiple, independent instances of TEditadble- 
GalleyText objects. Supports multiple flows of text, such as arti- 
cles in a newsletter. 


TT CRELANG ico Lue eseeidestavesvecnes Component of a formatted paragraph. A light-weight object used 
to render the text of a paragraph. 
TT EREIOMeOn b ossidce te ivisuitevicne This class is used to stored information about a paragraph that has 


been “decomposed” into the atoms it comprises. This structure 
is used to cache information such as the widths of elements 
within a paragraph. Such objects are also the basis of Knuth- 
style text formatting and greatly speed the processing of text 
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with Knuth’s algorithm as a fair amount of time spent format- 
ting text in TeX is allocated to parsing the input. Both fast and 
high quality text formatting algorithms can make use of this 
concept. Also, by isolating the intelligence required to decom- 
pose paragraphs into words in an object such as a parser (see 
below), internationalization is simpler. 

TP ATSOR io caitectasecpatenkshenines Class whose function it is to tokenize the text associated with a 
paragraph. For English, this amounts to breaking the text into 
words (and punctuation, if hanging punctuation is desired). 

MT ach abl es sisicsorivcavsesetcnties Mix-in for views supporting tracking protocol. This class provides 
common protocol for all views that may become trackers (for 
“handing-off” of tracking in multiple view situations, etc.). 
This class should be mixed in to any view that may participate 

in tracking the mouse. 

TL ORED ACKEl 2c eceeeseasendes Class used to track the mouse around multiple text views. An ob- 


MBaseText View... mmon functionality shared: 
hiefly in the form of linkin 
irevious page, next page 
d stretchability protocé 
...Class implementing the area into 
Roughly analogous to a column jations. The inter- 
action between this class and th class determines 
breaks within a paragraph View object is instan- 

or..this view, then th relat 

at enclosesit. { 


Tlext View........ hould be set. 


ere meccesenweeeccereseorces 


ted uch as cut, copy, pa 

fication of highlighting will no 

yf the user interface issues are resolve 
about direct manipulation of text. For the sake of this ERS, I 
assume that there will be, at a minimum, some type of “on,” 
“off,” and “dim” highlighting protocol, and that it may be up 
to ZZText to define the protocol for blinking the insertion 
point. 

TTextCommandd....ccccsevcceee: Base command object for text editing. Undefined for now, but 
will likely descend from TCommand or something similar. The 
exact definition of this class will wait, pending work by Arn and 
Larry in the areas of undo, redo, and voodoo. 


TCutTextCommand, 

TCopyTextCommand, 

TPasteTextCommana, 

TStyleCommand, 

TFormatCommana, 

TInsertText Command .......... Refined command objects base on TTextCommand (above), im- 
plementing the various text commands. These classes will sup- 
port the Pink “clipboard.” 


Se a i eee SSS 


é Registered /Restricted e ZZText Layout and Editing Classes ® March 15, 1990 ° 2/259 


ra 


sass) Ann py, puv mnohvy Dayzz 


O66I ‘ST Yu yG 


SLL 


pansssy/ pansy 


me ee ee ee ee men em ee ee ee eee ewe ey 


TTextElement : 


TParagraph : 


TSimple- 
Paragraph 


Neca he Ra COK a ek Re a ee 


TTextLine 


TChangelnfo 


a NOR ea 


TGalleyText 


PN SASNAA APSA IOI Pate 


TEditableText 
y: 


BVI CMR I NOLS ie 


we wee em wm mew wm ee we ee new ea eee eee cee eww ewe eee ewe aw wacwasocoe oes 


pe a a a a ee em ee me ee ee ee eee eee 


TEditable- :  TEditable- 
SimpleText GalleyText PRD eee ToT 


TGalleyManager 


77Text Classes Familv Tree 


TContainerView* }} 


END IIN  ONe NES RATE Eee nrenrarr rrr (63 


Ss ESSE? e crt sir ese a 


juvbastegeet ees TPageView 


te 


Sy 


Ce seine g ear Bonen 


Reference 


A Inheritance 


* Class not.defined in Elite 


aatateneanetan pearacanaeat dance uN ny 
srioaneionge atin antennae enone 


prrnsssdy,/ pasa sway, 


e 
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67 OLE 


- 


- ~ - 


User View 


‘his is some styled: 
itext in a galley ob- 
ject. 


er take text tod 


Text within a gal- | 
‘ley object may be : 
styled, and galleys | 
contain paragraph | 
information. 


Notes: Multi 


This is some 


The text in this view..i36° ...flows into this one. 


a re is 


ben eee ew ee ee tee ee 


Views, Galleys, and Text 


~ 


ple views of the same text would be 
implemented at the user view level. 


Page views descend from TContainerView, 
but the links between TTextViews is independent 
of all TView and TContainerView information. 


MBaseTextView 


This class implements behavior allowing a view 
to be linked to views logically “before” it and 
“after” it. Both TPage View and TTextView descend 
from this class. Conceptually, a descendant of this 
class may represent either a column of text or a 
page consisting of columns of text (but not both 
simultaneously). Linked objects of class TTextView 
are analogous to columns, while objects of class 
TPage View are pages, or groups of columns. 

One area requiring great flexibility when han- 
dling text is what to do when text hits the edge of 
the view, whether the edge is a side or the bottom. 
In order to provide the greatest functionality and 
flexibility, ZZText supports two SOND: ie 
stretch limit and the grow limit: Wh 
runs the stretch limit, th: 
Overrun is invoked. Whei 
limit, the method Grow 


underflowing a view. 


As an example, con MacDraw: when a user 


automatic stretching of the box that outline’ 
text is the “stretch limit,” and the automatic | 


Note that 
the region into 


This is some sample text. 
Here is some more sample 
text, which is not as nice as 
the first sample text but still 
better than about ninety- 
nine percent of other sam- 
ple text. Honest. 


UE SLL LSOULLLOEAY pit LEU RU UE EA RE 
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Diagram of Stretch and Grow Limits 
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gular. Also note that this has nothing to do with 
text that gets pushed into a new region as a result of 
an insert if that region already exists. If an 
“overflow” region is available (the is a view in the 
chain following the current viewl), then the current 
view is not grown and text is “flowed” into the 
available region. 

For text processors, ae default behavior will 
likely be not to grow or stretch a view when it is 
overrun, but to put the overflow text into the next 
view in the chain of views. This behavior is auto- 
matic if the pointers to the stretch limit and grow 
limit rectangles are both nil. There is a subclass of 
TTextView called TStretchableTextView that 
implements the stretching and growing behavior. 


pt of an area in 
mn). Text may flow 
fer text view, or the flow 
and flow into following 
provisions exist regarding 
at does not fit into a text 
ther view, en- 
MBaseText View 


Stretch Limit 


Grow Limit 


ae 
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on how it will look. In addition to the properties of 
a text view, other views may define a relationship to 
this view. This allows such functionality as automat- 
ic adjustment of the origins and sizes of views when 
footnotes are added, as well as aligning baselines in 
adjacent views. 

Lines belong to paragraphs (which generate 
them), but are used to present the text given a par- 
ticular view. Normally, a view neither creates nor 
deletes lines (this is done by paragraph objects ex- 
clusively). However, it is desirable to maintain lines 
without necessarily maintaining paragraphs. For this 
purpose, views may occasionally manage line objects 
directly (they never create them, though they may 
delete them some time after the paragraph that gen- 
erated a particular line has been deleted). 


fit. In addition, text views 
shift up and down as text 
particular, pushing lines 
pulling them back is h 
itself. : 
If there is a shape 
the shape defined by: 


example of establishing three views 
gether, follows: 


TGPoint sizeAB(200, 145); 
TGPoint sizeC (415, 200); 
TGPoint -locationA(5, 0) 
TGPoint locationB(220, 0) 
TGPoint locati 155); 
TTextView* TText View (sizeAB, 
locatio . 
TText View* 
locatio 
TTextView* cV. 
locationCc) ; 
aView->SetNext (bView) 
bView->SetPrevious (aView) ; 
bView-—>SetNext (cView) ; 
cView->SetPrevious (bView) ; 


TStretchableTextView 


This class is essentially identical to its superclass 
(TTextView) except that this class implements the 
strech and grow protocol described above. Note 
that stretching and growing is not the default be- 
haviour of TText View, though the paragraph classes 
always attempt to stretch a view before overrunning 
it, if there is no next view in the chain. 


TPageView 


This class is a container view for objects princi- 
pally of class TTextView. Its chief purpose is to 
group objects of class TTexrView together in a way 
that allows computation of such typographic re- 
finements as matching column depth, overleaf page 
depth matching, etc. Note that this class is a sub- 
class of TContainerView, rather than TView. This is 
a result of the notion that pages are simply view ob- 
jects that clip elements to their boundaries. In an 
application such as MacDraw, this is not necessarily 
the case. 


TrextLine 


pointers not to match (if 
view but not the first in 


TParser 


This class is responsible for decomposing the 
text of a paragraph into “words.” In early versions 
of ZZText, this will support only languages with 
relatively casy-to-recognize word delimiters (like 
English and spaces). It also recognizes punctuation. 
The interesting thing about this class is that it is in- 
cremental. That is, given an arbitrary insertion or 
deletion (or combination), this class performs the 
minimum work necessary to restore the target para- 
graph to a state of full tokenization. 

This method is extremely fast, and has two 
positive results: the tokenized paragraph can be re- 
formatted much faster in the simple case (adding up 
widths until the line overflows) as only a few addi- 
tions are needed per line. In addition, since Knuth’s 
paragraph breaking algorithm uses tokens, the para- 
graph is already in a handy state for “optimization.” 
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The incremental aspect of this class is carried 
one step further: it can split a paragraph into two 
paragraphs by retokenizing the affected text and 
then moving tokens following the paragraph break 
into a list of objects for the new paragraph. In addi- 
tion, a parser also may join together the token lists 
of two paragraphs that become one as a result of a 
deletion. This is analogous to the split case: the text 
is retokenized and the tokens from the second para- 
graph are added to the list for the first. The second 
paragraph is then deleted normally. 


TTextElement 


This class implements text tokens for format- 
ting. Basically, tokens are words (in languages that 
have the concept of a word; notable exception 
clude the Thai script). Ea¢é 


punctuation and other 
are considered text elem 

Tokens maintain 2 
paragraph to which 
contains its width, hei 
trailing white space 
of the token. Note 
index of the first elé 
the current and previcts: tk 
tained by a parser object, m us 
mation redundant. By omitting this infor 
indices need not be adjusted when inser 


tokenization process very fast. Tokens are cr 
and destroyed by an object of class TParser. 


discarded, if nece 
paragraph that 
ized automat 
description of the 


TChangelinfo 


This class implements a cache of information 
needed by the pagination methods. It does all 
records-keeping required by the incremental refor- 
matting code. Among the elements kept track of by 
this class are the index of where reformatting should 
resume following suspension to handle user input, 
the range of text affected, whether or not the refor- 
matting process is interruptable, etc. 

This class also remembers where drawing was 
suspended when lines are being drawn into a 
TlextView. Again, this occurs as a result of user 
input interrupting the reformatting code. Note that 
both the reformatting process and the redrawing 
process are incremental and interruptable. If the 
change affects the document in a way that is not in- 


terruptable, it is normally the responsibility of the 
client’s code to disable formatting/drawing until 
the critical section has been updated. Note that the 
interface for controlling interruptability, etc. is part 
of other classes, such as TEditableText. 


Trroperties 


The properties of a paragraph that control the 
way a paragraph looks are not stored with the para- 
graph. Instead, they are stored in a paragraph prop- 
erty sheet, one of which may suffice for many para- 


graphs. 
Rather than attempt to implement all of the 


sonary (see the 

(tokens) with 
values. The token 
header for the la 


cessed via syntax: 


mum line spacing» 


Note also that the arithmetic for calculating an 
unconstrained line spacing value is a first-order 
polynomial (of the form y = mx + 6), where x is the 
natural line spacing derived from the height of the 
tallest font on the line (¢y., ten points), 4 is the 
leading value (¢g., two points), and m is the line 
spacing multiplier (¢y., 1.2). For this example, y 
would be 14 points (y = 1.2 x 10 +2). 


—— 
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TParagraph 


A protocol-only class defining the basic 
behavior of paragraphs in ZZText (note the pro- 
tected constructor in the class declaration). 


TSimpleParagraph 


This class supports a relatively light-weight 
paragraph with respect to the number of member 
fields. “Simple” is somewhat cuphemistic, as this 
class implements all protocol for breaking a para- 
graph into lines, albeit simplistically (hence the 
name). The basic "algorithm for line breaking is first 
to make sure that the token list is up-to-date by in- 
crementally retokenizing the paragraph to 
accommodate the most re t H 
line before the first line 
found and rebroken (so t 
onto the previous line are: 

At this stage, a gu 
which TTextView lines s 
wrong, but the error m: 
view that comes befor 
guess is made. This wr 
is determined that t 
mainging in the “gué: 


ld go (this guess can be 
r be to put: the line into a 
le correct view if a wrong 

ris-detected when it 


overhead needed to do ee text oe 
aoa of class TSimpleParagraph are able to. 


is not interruptat 
ting and pasting) 

Choosing a long p may 
delay. The interaction between this class and 
TTextView represents the most complex area of ZZ- 
Text, chiefly by virtue of the fact that these two 
classes account for most of the code in ZZText 
(scrolling, painting, measuring, etc.). 

In general, the formatting process generates 
lines as atomic units. As lines are generated and as 
the last character position directly affected by an ed- 
iting change is passed, new lines are compared 
against old lines to determine when new lines are 
no longer being generated. When this occurs (lines 
have “re-synchronized”), formatting stops. If a cli- 
ent should choose to override this behavior, ex- 
treme caution is advised. Even if you know what 
you’re doing it is easy to get this wrong. 


TFancyrarag raph 


This object has nothing to do with calculating 
minimal updates for painting text as it is typed; that 
behavior is implemented in class TSimple Paragraph, 
the superclass of this class. The chief function of ° 
this class is to provide a “beautification” method 
that may be invoked on demand, or automatically 
via some “beautification process.” 

The superclass provides a fast, first-fit algorithm 
(stuff text until there’s too much, then stretch the 
spaces to justify, with no hyphenation) to give the 
user an idea how the paragraph will look. Some 
time later, the beautification method is invoked 
when it will not interfere with the user, and a new 

“optimum fit” set of line breaks for the paragraph i is 
calculated. The new line information is substituted 
for the old, and if the paragraph is visibles:pr 


uch the text is associated 
‘results from the fact that 
mo information about the 
fit (since this may vary de- 
- of the text). To understand 


5 five (the index 
where the next chara serted). The style 
at this index is the old one, not the new style estab- 
lished for typing. This class compensates for this 
condition, and others, including deletions and using 
arrow keys. 

Clients should not normally deal with this class 
directly, or even be aware of its existence. This de- 
scription is included for completeness. 


TGalleyText 


Clients will note that this class is derived from 
two classes representing styled text and runs of 
paragraphs. The implementation of this class is 
roughly similar to the implementation of style runs 
(please refer to the diagram). 
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It probably will be true that the algorithm for 
removing tokenized paragraphs from the tokenized 
paragraphs list will never “un-tokenize” a paragraph 
that is also on the ugly paragraphs list. 

This is the class used by TEditableGalleyText to 
implement storage and run maintenance. 
Specifically, this class implements runs representing 
paragraphs (complex paragraphs—not the “fake” 
ones used in class TEditableSimpleText). This class 
controls the number of paragraphs that may be to- 
kenized at one time, as well as maintaining the list 
of paragraphs that have not been “beautified.” 


TEditableText 


This is essentially a protocol and support class 
forming the backbone of the.ather. twa. editable text 
classes: TEditableSimpleTe 
Text. It insures that the t 
and implements some of 
shared by the more refined 
deletions. 

TEditableText maint 
style controls the ap 
appropriate. In additio 


the mping style. This 
ce of text as it is typed, if 
Is are made auto- 


date information used e the af aretion: ¢ 

One other area of support provided by" tha 
is in the area of idle time processing. Format 
and painting are interruptable and are resumed 
tomatically whenever user input Is not pendin 


TryToFinishForm 
ridden in subcli: 
to determine if 


TEditableSimpleText 


This class implements a relatively lightweight 
editable text object. This type of text object should 
be used in the text edit fields of a dialogue box, for 
example. Paragraphs are not supported directly by 
this class, as they are implemented in classes that de- 
rive from TGalleyText, and this class has as its foun- 
dation an object of class TAdjustedText. Note that 
this class give the appearance of simple paragraphs 
by indenting the first line following a carriage re- 
turn. At most one line in each pseudo-paragraph 
may be indented (note that TEditableGalleyText 
supports multiple line indentation, including hang- 
ing indentation). . 

All “paragraphs” in the text backing up an ob- 


client’s most recent chan 


same TProperties object. In reality, there is only one 
paragraph (just the appearance of multiple para- 
graphs) in this class. 

TEditableSimpleText should be used in cases 
where the text is relatively short (dialogues, etc.) 
and minimal formatting is required. This class is not 
recommended for button labels, etc. (it’s too ex- 
pensive). 


TEditableGaileyText 


This class and TEditableFancyGalleyText are the 
principal classes used to manipulate single flows of 
text through one or more views (derived from class 
TText View). This class insures that all paragraphs af- 
fected by an editing change are updated before con- 


trol is returned to the client. a is ; not pessreptive 


ed, at least locally, i ge 


irectly affected by the 
pdated. For example, if 


”fneeruptbl until both 
.rebroker nd redrawn. 


views dur- 


ing idle time draws age 

If a client desires only one text flow (through 
one or many views), this class is recommended. To 
use this class, establish an initial view (or views, 
please refer to the code fragment in the TTextView 
section) and do the following... 


TEditableFancyGalleyText text (firstView) ; 


...and that’s it. The client has the option to 
specify a different default typing style (the system 
default style will be used in the absence of a client- 
specified style), and the default property sheet may 
be changed arbitrarily. For example... 


sizeStyle = new TPoints10(); 
text .TypingStyle () ->AddStyleToSet (sizeStyle) ; 


THangCountStyle hang(1); 


ject of class TEditableSimpleText must share the 
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THangAmountStyle amount (24.0); 
text .DefaultProperties()->AddProperty (hang) ; 
text .DefaultProperties()->AddProperty (amount) ; 


...sets the default type size to ten points and 
sets indentation at a third of an inch for the first line 
in each paragraph. 


TGalleyManager 


This class manages multiple text flows, such as 
the articles in a newspaper. For the sake of discus- 
sion, the “active galley” is the one with the blinking 
insertion point; the one into which non-positional 
events will be directed. The principle role of this 
class is simply to maintain a list of objects of class 
TEditableGalleyText, and to re ll 
is the active one. E 

This class gets involved: 
selection object as the no 
such that the “active gall 
tion” (see below). 


TEditTextSelection 


This class is a: 
(defined in the base C 
of the editing pecs 
Class TEditableText maintains 
(multiple, discontiguous selections ar 
although exactly how they will be used 
clear). 

All objects of class have at least one objec; 
class TEditTextSelection in a list of selections. TF 
selection always heads the list of selections, and ¢ 
never be deleted .or put: ywhere in the list ot 
than at its head 
is automatically 
sitional events. Th 


would not know if its s target has been removed. 


Examples 


This section will be rewritten eventually. 
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Open CGuesiions 


¢ Tracking, selection and auto-scrolling? 


e What about a system-level style manager? 

One item not covered in this document is 
how background tasks that have completed 
updating a part of the document (¢.g., a para- 
graph) will synchronize the update of the dis- 
play with the current user activity. Later. - 


Headers, footers, footnotes, table of contents, 
etc. The specification of these will come fol- 
lowing some more discussion with the Jane 
Folks. For some things, (table of 
some type of active value m F 
good idea. 


Commands and# 
look like in 
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1. Overview 


What Line Layout is 


Line Layout is an extensible set of objects used to display single lines of fully styled text. Besides 
displaying text, Line Layout also provides methods that aid in the measurement, selection, 
positioning, and highlighting of characters. Line Layout is for the rare programmer who wants to 
write a text formatter. The avarage Pink application programmer should not use Line Layout, but 
should use ‘higher level’ objects such as ZZText objects for text display and editing. 


A rich set of typographical formatting controls are handled automatically by Line Layout. The 
typographical control supported by Line Layout is a superset of the controls provided by high 
end programs available on the Macintosh 


Line Layout also provi 
systems. This enables. 
formatting features 


Line Layout handles ext in one of two fundamental directions: ho 
nes can be formatted for right-to-left or left 


distinction needed 


What Lin 


Line Layout is not a textedite 
It also has no “user interface” pe 


Line Layout does notunderstand anythin 
single line or line segment. In particular, p 
space” or general paragraph appearance a 
Layout does not.deci 
However, Lins 
services dea 


Why use | 


The reason an application should use Line Layout is that it hides the complex details required to 
support foreign languages and high quality typography. An application programmer using Line 
Layout and following a few simple guidelines should be able to create foreign versions of an 
application with little or no code changes. 


Also, the toolbox internally uses Line Layout to display text in everything from dialogs to 
window headers. The standard text editor is also written on top of Line Layout. Applications that 
implement their own layout algorithms risk having a different and possibly incompatible human 
interface. 


a e  man 
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2. Where Line Layout Fits into the System 


Line Layout sits on top of the Graphics and Font system, and on top of the low level toolbox. 
These systems have no textual interfaces and are not dependent upon Line Layout. The following 
is a brief description of the pieces of the system that fit together to get text to display. 


Graphic System (Albert) 


Line Layout sits on top of the graphic system. Communication is one way, Line Layout instructs | 
the graphic system to draw or highlight objects. Line Layout does not use the graphic system to 
obtain character information, including hit-testing information!—Line Layout does its own hit- 
testing. 


Low-level To 


For the most part, the f ust ace. Line 
dasses and the Collectit 


font mechanism to decid 


Line Layout 


Low-Level ToolBox: 
includes styled text and collection classes. 


Graphics System 


Figure 2.1 


1 Hit-testing is the process of mapping a mouse or cursor position to an object. Normally after 


an object is ‘hit’, information is visually passed back to the user indicating that the object can 
be manipulated. 
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3. Important Concepts 


This section deals with concepts that are fundamental to Line Layout and to this document. 
Appendix A contains a glossary of other concepts that are also important but are more commonly 
understood and are not as fundamental to the understanding of this document. 


Characters, Glyphs and Unicodes 


A character is an abstract object having a single and unique semantic or phonetic meaning. 
Glyphs represent graphical appearance of characters. For example, the glyphs A, A, A represent 
the character A. 


Fonts contain a set of 
different glyphs for tt : 
font and character cas aining glyphs 
from a font. Line La : : 


ter or characters. Different for: 


it, a given character 
and two or more 


‘orms. Within a font, ea e4 


A complex font is a font that contains information associating some glyph IDs with certain 
combinations of characters and rules. For example, there may be some information in a font that 
associates the glyph ID $1A01 (which happens to have the appearance ‘fi’) with the combination 
of the two characters $0066 (“lower-case f” semantic) followed by $0069 (“lower-case i” 
semantic). Any font that contains no such associative information is called a simple font. The 
glyphs in a complex font divide into two classes: rendering forms, for which combination rules 
appear; and character glyphs, which have a one-to-one correspondence with character codes. 
Rendering forms include ligatures, applied marks, and contextual forms. 


Fonts provide Line Layout with the information needed to make typographic and script 
formatting decisions without a user’s explicit involvement. This contrasts with traditional 
systems where a user must make an explicit decision on a font by font basis—as a result users 
settle for low quality output because the burden is too great. 


The Bass outline font documentation provides more information about the structure of fonts. 
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Styled Text 


Line Layout makes heavy use of Styled Text objects. The application programmer must 
understand how to use Styled Text before he can use Line Layout. 


The styled text object is the collection of characters (also known as the backing store) that 
comprise the text for display by Line Layout. All editing of text object is an application’s 
responsibility. An application is also responsible for passing a text object to Line Layout for 
display. The characters in a text object should always be phonetically ordered as appropriate for_ 
the language represented by the characters. Line Layout will display characters in their correct 
visual order if the characters are phonetically ordered—the next section shows why the two 
orders are different. 


A text offset (or character offset) is an index between characters i in a text object. A text index i 
index of a character ina text object. FhIs distinction 1 
characters rather than: 


the 


Reordering 


A text object is an: 3 netically ordered. 
Ani . her than their written 
act of the 


order and not 
English should: 
_ bears repeating: Line y 
reorder glyphs as needed for displa 
Arabic mixed with English. 


As a consequence of reordering character 
between text offsets (or insertion points) a 


For example 
rafter the py 


dus line or at the st 


Appendix A pr about character reordering and 


2 This phonetic ordering facilitates many processes upon a text object including text input and 


parsing. 


Sc 
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Character Ordering vs Line Direction Script Ordering 


Assume that characters typed in as ABCD appear as DCBA—as characters might 
in a script that flows from right-to-left. Also assume that the characters efqh 
appear as efgh—as they normally do in a Roman script. The ordering of these 
characters within a script is refered to as the character ordering. 


Character Ordering 


Assume characters typed in as: 


AiB IC|D. ——_ appear as: —IpniclBla 


A problem occur HEN: SCTIPIS: WHC. 
i § Case a line conmanine athe text ABCDef 


solved i in line layout by 


ht , to horizontal lit 


numbers, spaces:ank 


Highlighing the contiguous characters CDef in the text 
string yields the logical, but strange and correct results 
shown below. This is known as discontinuous highlighting. 


Figure 3.1 


a 
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4. Features of Line Layout. 


This section describes the various Line Layout features that are visible to an end user. The major 
part of Line Layout’s work is the construction of layouts that describe the appearance of a line of 
text. To construct a layout, Line Layout needs not only a source of text, but also style information 
and other options that affect a line’s appearance. Four classes of features act together to transform 
the appearance characters into glyphs, and act to position glyphs. This section list these features 
by their class type. These class types are: Graphical Features, Layout Features that Affect 
Character to Glyph Mappings, Layout Features that Affect Glyph Positions and Glyph 
Adornments. 


One important thing to keep in mind: the layout features described below are mandatory for 
international text, which has many attributes that low-quality English text never needs. While 
these features are optional for English, they are vital to the correct rendering of text in many other 
languages. 


The human interface 
individual applicatio: 
features offered by 


are an application’s responsibi 
andard) features. Listed .bé 


standard” 


af 


xd here. The actual 
the section System 
ed to implement a 


Appendix A provi 
system styles and # 
Defined Styles— 
human interface; 


dditional detailed information for many 
sthod required to control these features ca 
is:of.interest only to application programm 

ites presented in this sect 


Graphica. 


The graphic and font engine suppo s 
Layout: 


e Text Color 


Text canbe styled with any color. 


A Uses it'size, including fractiona 


The graphic feature set will be expanded to include outlined characters, bold characters, all your 
favorite Macintosh character styles, and more. 


Layout Features that Affect Glyph Mappings 


The following features affect character code to glyph code mappings: 


e Font 


Text specifies a font for display. If a font is not available, appropriate defaults specified 
by the application or the system will be chosen. Fonts are specified by their name rather 
than by an ID number as on the Macintosh. Outlining and shadow effects are a function 
of the graphic system and are currently only specifiable as a separate font. 
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Line Layout will display a missing glyph symbol for a character when a font does not 
have a glyph for that character. In the future we may provide an alternate user interface 
for missing characters; one where we try to find missing characters by dynamically 
scanning a font hierarchy until a missing character is found. However, Line Layout 
would need support from the font cache and/or font manager before such an interface 
could be implemented. An editor should use a similar font substitution mechanism to 
style text appropriately. This would allow a user to type any symbol or character without 
switching fonts. 


Ligatures — 


Fonts can instruct Line Layout to display sets of characters as a single glyph. For 
example, an ‘A’ followed by an ‘”’ in some fonts will display as an ‘A’. More commonly 
fonts display ‘f’ and ‘i’, and ‘f’ and ‘l’ with ligatures, but character pairs like these are best 
display using contextual forms (described below.) 


ttachments 
ry the charac 


aa 


a ter. Unlike ligatures, characters. 
d on the fly and do not suffer from the combi 


‘f. A user need not 
provide the correct result in’ 


Current Macintosh users must m 
5 or 6, and manually verify that the 
missing, the user must delete the ck 
parts:of the-contextual form. Additi 


Line Layout automatically reorders characters, per a font’s instructions, for characters in 
Indic languages. For example, a word typed in as ‘hello’ may display as ‘ehllo’ in some 
scripts. Current systems force users to type the characters according to their visual 
appearance as opposed to their spelling. 


Layout Features that Affect Glyph Positions 


The following features affect the placement of glyphs: 


Super/Subscript Positions 


Superscripts and subscripts are relative to the baseline and proportional to the font size. 
For vertical text the baseline is usually down the center of characters, and 
super/subscripts are to the right and left of the baseline. 


ear aan 
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e Letterspacing 


Letterspacing is for moving pairs of characters closer together or farther apart. The 
amount of movement is proportional to the font size of the characters that contain a 
letterspacing style. Letterspacing is also known as manual kerning. 


e Kerning 


Kerning automatically shift pairs of characters closer together or farther apart. The pairs 
can shift in both the horizontal and vertical directions. The behavior of the shifting is 
identical with letterspacing and super/subscripts—the difference being the kerning 
amount is froma font and the letterspacing and super/subscript amount is from a user. 


¢ Tracking 


Character widths.can.be-expanded.or.contracted by applying a tracking value to a. 
to the width of characters. A font 
‘lyph widths using the multi 


d orcmcéned 


4easurement on either 
y into a margin. Ina 
if the line 


end of a li 
Roman 
is right f 


Justification is the ability to: 
Layout preforms justification by 
other characters in a hierarchica 
white space characters until a use 


e Overhanging:pt sation/ Optical alignment 
These features allow characters specified by a font to ‘hang’ into the margins. Optical 
alignment gives the illusion of characters being flush with the margin while they really 
hang over the margin. Overhanging punctuation such as quotes allows punctuation to 
hang into the margins. This allows text to appear flush left or right from line to line, with 
or without punctuation. 


e Character Direction 
Character direction allows characters typed in as ABC to be displayed as CBA. A 


character's Unicode determines its character direction. A user can override a character's 
default direction. 
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e Run Direction 


Run direction controls the relative ordering of a blocks of characters. A block or run is 

_ defined as a sequence of characters all with the same Character Direction. A character’s 
Unicode determines its run direction. Line Layout uses Run direction when mixed scripts 
such as Arabic and English are on a single line. Users can override a character’s default 
Run direction—this is necessary in Arabic and Hebrew because sometimes Line Layout 
cannot format a line as a user wishes because the correct formatting is ambiguous. 


Glyph Adornments 


An adornment is a graphic applied over a run of glyphs. Adornments do not affect the placement 
of characters. Adornments are extensible—ie, new adormment styles can be added to text by the 
addition of anew adorn . This following lists the standard set. 


‘cified for text. AS ang 


/subscript position. 
their color. 


e Overbar 


Same functionality as a single 1 


ee 
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5. Objects for Displaying and Hit-testing Text 


The following is the set of objects needed by an application to display, highlight, and hit-test text. 
Two of these objects, TCaretPlace and TInsertionPoint, are used only for hit-testing. 


TStyledText 


As stated before, a styled text object is used by Line Layout as a source of characters for display. 
The Style runs in a styled text object also control many of Line Layout’s features. : 


TCaretPlace 


A TCaretPlace is a descr 
caret. The actual appe; 
in pairs from a TLayor 
However in certain 
two carets separatel; 


ould be placed and the supscsted. 


rets are necessary, an ; 


uses a TinsertionPoint to. 
mapping is known as hit-testing. 


Line Layout also uses a TInsertionPoint 
Applications need to use Line Layout facil 
because a caret position depends upon the 
direct access 1 ne orders except thro 


TLayout 
TLayout is the object that computes glyphs from characters and then positions glyphs. A TLayout 
can format, display, highlight, and hit-test text. A TLayout also handles typographic and script 


specific contextual formatting constraints that are either specified with the characters, determined 
froma font, or defaulted by the system. 


A caret is a graphical indicator between characters in a stream of text. On the Macintosh a 
text caret appears as a blinking vertical bar. It is also known as the ‘insertion point’. 


A TextIndex is a zero based ‘array index’ into a text class used to extract a character at the 
index. 


2 A character side indicates if a hit ocurred before or after a character. 
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6. HowTo Use Line Layout 


This section describes how to use a TLayout object to display, highlight and hit-test characters. 
Note that in future versions of this documnet more examples will be added. 


Setting Up a TLayout 


Through the TLayout::SetText call, an application provides a TLayout with styled text, a style set 
of line specific information, justification information, white space trimming choices and an origin. 


A TLayout operates on a TStyledText object. Normally text will have a font, point size and maybe 
language styles specified. The complete set of possible styles are documented in the separate 
section System Defined ey ee Ot Si vie Styles are of little interest to the average user. If text 
lacks any particular styh ; Sea system—or sata ERS default. It: 
important to note tha 
application. Certain a 
affect linebreaks, glyq 
defaults in a gracef 


4 default origin of (0,0) if an origin is not s 
tion to a with things like mous 


The line direction style is part of the line 
styles are searched for first in the line sty 


or perhaps as a sep 


Displaying text 


To draw a line of text an application must create a TLayout using the parameters described 
above. Then, all an application has to do is call TLayout::Draw and pass a port. For replicating a 
string, it is very fast to redraw the string by changing the origin on a TLayout and calling 
TLayout::Draw. This is faster than calling TLayout::SetText multiple times. 


EXAMPLE : The code below can be used to display an array of Unicodes in 
24 point Helvetica. 


#ifndef — LINELAYOUT _ 
# include <LineLayout.h> 
#endif 


TLayout layout; 
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TFillBundle white (Oxffff, Oxffff, Oxffff); 


void 

DrawString(TGrafPort* port, TGPoint &ppoint, UniChar* text, unsigned long len) 
//Create the styled text object. 
TStyledText styledText (text, len) 
TTextSelection textrange; 


//Style the text 

textrange.SetRange( (unsigned long)0, styledText.Length()); 
TPointSizeStyle size(24); 

TFontStyle font (“Helvetica”); 

TStyleSet styles; 

styles.AddStyleToSet (&font) ; 

styles.AddStyleToSet (&size); 
styledText.SetStyleInRange(&styles, range); 


}? 


It is important to 
the state of the 
necessary, Or a 


TLayout::Draw say 


seesaw! 


: ing g Pons. To prevent flickering when a lit 
recommend double buffering, Double buffering is a graphic technique where entire . objects are 
displayed into an offscreen bitmap and then the bitmap is displayed to the screen—without 
clearing the screen first. 


Note that re-highlighting an area to give the affect of de-highlight glyphs will not work because 
highlighting is not always an invertible function. When deselecting text, an application must 
redraw a line and re-highlight glyphs as needed. 


Note that Discontinuous highlighting can occur when a user selects a partial line of text when the 
line has glyphs that flow in opposite character directions—as is normal in Arabic. This will 
happen when the selection is of a contiguous range of characters in the text backing and when the 
glyphs associated with the characters are discontinuously ordered on the display. Using the 
normal point/shift-extend algorithms an application will get discontinuous highlighting free. 
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The next section describes an interface that applications can use to give the appearence of 
contiguous highlightings when a user selects text with a mouse—as opposed to using a find 
command to select text. . 


Hit-testing and Carets 


TLayout provides methods to hit-test glyphs and determine the TInsertionPoints associated with 
a “hit” glyph. A TLayout also provides methods used to determine the number and look of carets 


associated with a TInsertionPoint. The following is a description of how an application should 
use a TLayout to hit-test and draw carets. 


To map between a TGPoint (usually computed from a mouse position) and a TInsertionPoint, an 
application should call TLayout::InsertionPointFromPosition. An application can then determine 
where in the TStyledText -object-a-user-selected: Fo:extend a selection an application shoul 
compute a pair of TInsé 
application can easily 
highlighting. 


with the glyph at a; 
FromPosition but 


compute a new TInsertionPoint: 
obtained from InsertionPointFromPosi 
TInsertionPoint. Failure to use the routin 
within a line or carets moving in the oppos: 
an application’s responsibility to handle en 
previous line. 


An applica 
TextOffset 
needed by an 
slope of the mo’ it passes over slanted text. 
GetCaretAngleAreaFromPosition’—This routine is for changing the angle of the mouse 
"[Beam" pointer to match the slope of text it is over. This user interface makes it easier for 
clients to select italic text. 


Contiguous highlighting of discontinuous text is a feature where an application can give the user 
the appearance that text selected with a mouse is contiguous though its backing may really be 
discontinuous. Users seem to prefer this interface as opposed to showing a discontinuous 
selection. A TLayout will provide the additional routine below to help applications implement 
contiguous highlighting if they so wish. 


6 Currently these bad behaviors can be observed on the Macintosh with pre-system 6.0.7 
TextEdit in Arabic or Hebrew. 


' 7 — Routines indented in this document are not available yet and are only proposed interfaces. 
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TextRangeListBetweenTextOffsets—This routine computes the discontinuous text 
selection associated with the positions of two TextOffset on a line. 


Measurement 


Different parts of an application are interested in different types of line measurements. What 
follows is a description of the different measurments available through a TLayout. 


To find the minimum rectangle required to display a line, an application should use the method 
TLayout::BoundingBox. A BoundingBox is useful to determine what will need to be updated if a 
line is redrawn. A bounding box always includes all trimmed white space on either end of a line. 


To measure text for line breaks, an application should turn off justification and leave white spaces _ 
“untrimmed.” An application can then compute a line break by creating a TLayout for an entire 
paragraph and using the-method.TLayout:RistanceBetweenTextOffsets (with possible WOE 7 
break points®) to add, il they no longer fit ona line. | 


Once a paragraph h 


, 


find a line’s wid 
that the leading 
correct setting i 
Also, any ign 
is ignored willc 


To help align a particular glyph to" 
application can compute the amount 


GlyphInfoFromTextIndex—tThi 
associated with a TextIndex. This 


an application can use those insertion points for positioning the single glyph associated 
with the text range at some point. Applications need this functionality to align text to a 
decimal tab stop. An application can also use this routine to implement backspace code 
that backspaces over glyphs instead of characters. 


A TLayout assumes that the text between tab stops is a discrete unit. Applications must handle 
the positioning of text at tab stops themselves. To do this an application needs to use a separate 
TLayout for each segment of text between each tab stop and a line’s endpoints. Then the 
application must position each TLayout segment independently. The computations for 
positioning the segments are similar to the computations to position an entire line. 


8  Linebreaks possibilities can be determined using a the TWordBreak class and a hyphenation 


dictionary. 


ee 
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Finally the method TLayout::GlyphInfoFromPosition is for special purpose use to allow an 
embedded graphic within text to take the mouse tracker when the embedded graphic is selected. 
The section on extending the system will talk more about this. For most applications this method 
may be of little use. 


Justification 


A TLayout is passed justification information through the SetText interface. A target width and 
default justification parameters can be specified in the SetText call. The target width doesnot ~ 
include trimmed white space on either end of the line. The remainder of the justification 
parameters come from a justification style in the styled text object and are not final yet. However 
these parameters will control how much space can stretch, if Kashidas should be inserted, and 
maximum amounts other characters can stretch. 


The current impleme 
normal width and ev 
This will change. 


yyout stretches spaces up to thre 
i2 space among all the characté 


Line Breaking 


See Appendix D. : filled once some archite¢ 
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7. System Defined Styles 


Line Layout directly implements the styles listed in this section. Other text styles not listed here 
include styles for line height, paragraph line breaking parameters for starters and are 
implemented by higher level system objects. 


Please note that this section is not complete because all styles are not yet defined. 


Graphical Styles: 
e Text Color | 
TTextColorStyle is the style used for setting color on text. In the future this will be 


replaced with a style common to text and graphics—as soon as graphic lie can 
handle styles 


e Text Size 


TPointSi 
and fractia 


Layout St {fect Glyph D 


e Font 


e Ligatures and Contextual Forms 


TMet amorphsisStyle controls 


Ligatures and contextual forms have different levels of effect that a user can choose from: 


e The suppress level means no support (i.e. inhibit the layout feature). This might 
be harsher than expected: in Arabic, for instance, a value of suppress for the 
ligature feature would inhibit the formation of the usual lam-alif ligature. This 
setting should therefore only be used if the user wants to see something 
approaching the naked, unvarnished text source. 


* The mandatory level means to support only mandatory instances of the 
particular feature. For example, during rendering of Roman characters, Line 
Layout might only use anchor points in composing an 'é' for an ‘e’ followed by a 
‘“ in the text source if the "accent anchoring" feature level is at least mandatory. 
Roman kerning, on the other hand, might never be mandatory, and therefore a 
value of normal or higher might be needed to enable kerning. 
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* The normal level means to support "normal" instances of a feature. In Arabic 
ligaturing, for example, this level is required to get most of the normally used 
ligatures (such as “initial lam-mim"), assuming the font supports them. This is 
also the level that most font manufacturers will use for Roman kerning. 


e The optional level means to support any and all instances of a feature that the 
font supports. For example, an “a” followed by an “e” in English text might 
cause an “ze” ligature to be used if the ligaturing level is optional. The italic ‘st’ 
and ‘ck’ ligatures are similarly optional. Variant appearances of certain Chinese 
characters might be selected with a forms feature level of optional. - 


¢ The fifth option is default. Associated with each layout feature there exists a 
global default value. These defaults will usually be “mandatory.” 


, these layout features can be: 
range of characters. _ a 


style. We recommend that if a“ 
two of the possible eight choicest 
to explain to a user or even a pro 
for text that a user wants force rig 
to force left-to-right. 


péci 


fies super/subscripts amoun 


e Kerning 

— No interface yet. 
¢ Tracking 

— No interface yet. 


e White Space Trimming 
— No interface yet. 
¢ Justification 


— No interface yet. 


a a se ee ee 
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e« Overhanging punctuation/Optical alignment 


— No interface yet. 


Glyph Adornment Styles. 


Underline 


TUnderlineStyle is for specifying an underline, its position relative to a line of 
characters baseline, its thickness, and its color. 


Strikethrough 


TStrikeThroughStyle is for specifying a strikeout line, its position relative to a line of 
characters basetli thicknes TSH 


Overbar 


— No interf. 
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8. Extending the system 


An application can extend Line Layout with application specific features and new style types. 
These section describes how to do that. However, an application programmer first needs to know 
about a few more system objects and how TLayouts and these extra objects interact. Extending 
the system is straightforward once the fundamentals are understood. 


This section is not for the casual programmer who uses Line Layout to display and edit text 
strings. It is for the brave who what to extend line layout to display new object types. 


Additional Objects 


These following objects a 


ap characters to 
articular subclass 
t do not come froma 


of interest to cane 
“font file.” 


TLayoutGr; 


por 
A TLayoutGraphic is also responsi 
super/subscripting and tracking. 


associated wit 


An application can subclass a TLayoutGraphic and embed complex structures into a line of text. 
These structures can include pictures, graphics, and buttons. These structures themselves can 
contain lines of text. 


9 A glyph metric is information about a glyph’s geometry. A glyph’s width, height and 
bounding box is an example of a glyph metric. A glyph itself is a collection of curves, or 
perhaps a bitmap, that is used to draw itself. 


10 A fine point: A TLayoutGraphic actually acts like a font subclass and I would like to actually 


make it a subclass. However, a restriction preventing a font object to be initialized from 
another font prevents this. 
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What TLayout does 


A TLayout manages a complex interaction among different objects and object types. A TLayout 
determines glyphs and their positions by controlling the communication among TStyledText, 
TStyle, TFont and TLayoutGraphic objects and itself. 


A TLayout first handles the “bidirectional” reordering of character codes obtained from a styled 
text object. The reordered character codes are then broken into style runs and the style runs are 
then associated with a TLayoutGraphic. - 


Characters are mapped to font-specific glyph codes using the font associated with the 

TLayoutGraphic. The mappings can be one-to-one, many-to-one, and many-to-many —the more 
complex mappings result from ligature and contextual form rules. Character rearrangement, for 
use by Indic scripts and specified b 


also computes t! 
different from t 


is five pm." TF 
TLayoutGr 
either the 
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The time is five pm. 


TLayout 


TLayoutGraphic A amas TLayoutGraphic B < = TLayoutGraphic Cc 


He 1 


Font A 


Adding 


type of graphical style to text. For examp 
text. Secondly, a client may want to embe 


this can be d 


Adding New Styles 


Adding a new style type, such as boxed text, is easy. To implement a new style an application 
must create a new TStyle for a box, create a TLayoutGraphic subclass that knows about the box 
style, and subclass a TLayout to allocate the new TLayoutGraphic subclass. 


Subclassing a TLayout to allocate a TLayoutGraphic is done by replacing the 
AcquireLayoutGraphic and ReleaseAllLayoutGraphics methods. We recommend that an 
application initialize its TLayoutGraphic subclass from one obtained by calling 
TLayoutGraphic::AcquireLayoutGraphic. 


A subclassed TLayoutGraphic must be modified to use the new style type. If the new style will 
not affect default character metrics then the application is free to modify the DrawGlyphs, 
HighlightGlyphs, or AdornGlyphs methods as it sees fit. By the way, the AdornGlyphs method is 
called by DrawGlyphs to add graphical elements to a glyph that do not come froma font—like 
underlines. If metric information will be changed then the GlyphInfo, and the GlyphAdornInfo 
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methods need to be modified. The info method must be changes if widths or bounding box 
information changes as a result of the new style. 


Adding Embedded Graphics 


Adding a button (or other graphic) to text is not much more complicated than adding a new style. 
The difference is that a TLayoutGraphic needs to draw a button rather than asking a font to draw 
a glyph. Also the TLayout::AcquireLayoutGraphic method must be modified to create the 
appropriate TLayoutGraphic. The TLayout::AcquireLayoutGraphic method can determine if text 
is text or actually a button by looking at the style associated with the text. Two notes of caution: 
First, an embedded graphic object or button must be backed by a single Unicode. Second, a NIL 
TFont should be returned by the TLayout::Font method. 


Finally, a button may need to take the mou when a point down occurs over it. To ‘push’ the 
button, the applications é'for the line and determine a cha 
the same way it woul r could then tell if the hit occu 3 
button by checking th: the TInsertionPoint obtai ; mouse 
position. Once it has] occurred on a butto On of the button 
can be obtained fro romPosition method on can then 
hand the mouse tracker to a tracker associated with the button. 
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9. Performance Issues 


Caching of Information By a Client | 


A TLayout cannot take advantage of information obtained from previous lines. However, an 
application can. One set of objects that can be reused over and over again are TLayoutGraphic 
objects. 


The method AcquireLayoutGraphic can be used to cache TLayoutGraphic objects between lines. 
By recognizing that a TLayoutGraphic can be reused from line to line, a client can speed up 
performance by overriding the AcquireLayoutGraphic and ReleaseAllLayoutGraphic methods. 
To recognize if a TLayoutGraphic can be reused, an appliction needs to check if the parameters 


does not need to 
TLayout objects. 
An application s 


mmended that an appli 
parate TLayout for 


When Line Layout displays a line of 'té 
screen. Some application are time sens 
of Line Layout is a function of the input fré 
A good performance rule of thumb is that | 


superscript, : 
and punctuation should not overhang. 


Fixed Point instead of GCoordinates 


Currently TLayouts work with GCoordinates exclusively. These are big suckers!! and a layout 
uses a lot of them. Not only are they big, but they are slow to compute with. We may gain some 
speed and can reduce the size of a TLayout by using a smaller numeric type. Of course to use a 
smaller type efficiently, the path of glyph metrics from fonts though the graphic system need to 
use the smaller type. Otherwise too much time may be spent converting between types. 


11 The TGPoint for a single glyph is 20 bytes. A TGPoint is made up of two GCoordinates. 
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Appendix A— Concepts 
This appendix provides a more detailed description, with examples, of some Line Layout features 
described in Chapter 4. The features described in this appendix are: 

e Ligatures, accented forms and accent ligatures, 

¢ applied marks, 

* contextual forms, 

¢ automatic kerning, 


e automatic cross-stream kerning, 


A ligature is a rendering form that repres 
The word “ligature” is also used as a verb 
include the ‘fi..Jigature in English, and the 
a special typ it 


: a rendering form 
example, t &: 


CPA 
present in 


Applied marks 


An applied mark is a glyph that is composited dynamically with another glyph. The recipient 
glyph is called the baseform, and a baseform can have one or more marks applied to it. For 


example, Polish uses Roman script with some additional glyphs such as ’ 3’ If this glyph does 
not exist as a rendering form in the font, it could be created by dynamically composing the 
baseform ‘s’ and the applied mark ‘”. The composition process will ensure that marks are placed 
properly with respect to the baseform. 


Applied marks are aligned by anchor points. A glyph object associates a base glyph anchor point 


with each applied mark. Each applied mark has a single distinguished anchor point. This anchor 
point is lined up with the associated base glyph anchor point for rendering. For example: 
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Figure A-1 


Contextual fo 


A contextual form is at 
for example, has diff 
beginning, the middl 
Arabic letter “ha” t 
code is stored fore 


lyph that is used in certa 
yphs, depending on 

‘or the end of a word. Figure 2 illustrates this 

appear alone, at the start, middle, or end o 

; it is font’s responsibility to choose thi 


e "ha" 


A Roman font manufactur 
present the appearance of 


ombined ‘fi’ glyph. 
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Font has ligature: 


f+tis>f 


Font has contextual forms: 


sees ‘f’ followed by ‘i 


Automatic Kerning 


gether” naturally. 
Kerning is drive : ine how much t 


. An ‘o’ kerned wit 


Automatic Cross-Stream Kerning 
Cross-stream kerning allows the automatic movement of glyphs perpendicular to the line 
orientation of the text. This means glyphs move vertically in horizontal lines. Cross-stream 


kerning is driven via font tables to determine how much to shift glyphs. For example, a hyphen 
between two capital letters should be raised to reflect the centers of those glyphs: 


X-Y vs.X7¥Y 


Figure 5 — Cross-Stream Keming Example. 
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Optical Alignment 


Without additional information, glyphs may seem to line up incorrectly on the right and left 
margins. This is accounted for by two factors. First, glyph advance-widths contain a certain 
amount of extra white space to account for the normal inter-glyph spacing. 


This produces certain anomalies, since this space varies with the for 
different sizes of me font are left (or right) flush in QuickD 
up correctly: 


example, if 
not generally line 


The second that due to certain gptical effects, curv 
ke.them appear to line up, sor 
S are generally designed toe 


‘up with straight letters such as H. 


this reason, Cur 
baseline, so tha 


Figure A-7 


This same effect happens on the right and left edges of lines. In both of the following example, the 
center O lines up with the H’s, in the sense that the leftmost black edge of the H is even with the 
leftmost black edge of the O; this is shown by the line on the right. However, the letters do not 
appear to align correctly because of optical effects, as you see by looking at the words on the left. 


een EE 
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Hotel... Hotel... 
Other... Other... 
Hotel... Hotel... | 


Figure A-8 
To compensate for thes ical alignment i information. When jae 
the right and left edges % vs 
the optical right and 


available for vertical 


inctuation 


n:that hangs outside the text. This commonly 


er is a line that defines the position of the charact espect to other 
characters. The anporance of the baseline is illustrated by different sizes of characters; where it 
shows a stable point, out from which the characters grow. This is also the case with other scripts: 
the ascent portion of a character grows upwards from the baseline, while the descent portion of 
the character grows downwards. However, there can be dramatic differences in the general 
proportions of characters with reference to the baseline. If we were to take the naive approach to 
glyph placement, we would end up with something like figure 10. 
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Figure A-10 


In this figure, the baselines within a script match correctly, but the relationship between different 
scripts is incorrect. We need toalien:the:baseliries:on an inter-script basis, so that we canget 
something like figure be done manually. Howeve 
require the end user ti yning whenever size adjus 
within a line, or requi ave considerable knowl 


Pe ceeweweecwcocs, 


We have not fully worked out the means: 
to have fonts identify their natural baselin 
application specify (through a paragraph 
baseline. The shift a 
ation—the user int 


atural baseline, lets say Indic for ru : 

quary a paragrap iseline shift rule. A 12 point “Roman” } then decree 
that all Indic baselines within the paragraph should shift up 9 points. If a paragraph wanted to 
produce something like figure 10 it could return 0. 


The protocal between Line Layout and a text editor is simple. The hard part is letting the 
paragraph determine the shift amount. One possible mechanism is for a paragraph to have a user 
settable default paragraph baseline and a baseline rule. The baseline rule, when asked for a shift 
amount, can detect if the request is for a baseline other than the default paragraph baseline and 
can return the appropiate shift amount. 


The default baseline rule could compute the shift amount from some ‘user settable” template 
character associated with the line, paragraph, or document. From this template character the 
baseline rule can associate all possible baselines with a shift amount. 


nn yt a ee 
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Character Reordering 


A given text object may include parts that are rendered in opposite directions. For example, 
Arabic letters print right-to-left, while Arabic numerals and Roman script print left to right. A 
direction streak is a series of characters, next to each other in a text object, which belong have the 
same dominant rendering direction—left-to-right or right-to-left. 


A single line of text with streaks running in opposite directions can be formatted in two different 
ways depending upon the dominant line/paragraph direction. Figure 9 shows the possibilities— 
in this example line direction is refered to as run succession. 


Order of characters in the string: 


(w = space) © 


Even within a « 
backing store © 
it logically follows: the Word: 
“ihndi’. 


phonetic, semantic) order. Taking the exa 
codes in the order “hindi,” not in the ord 


order, and 


oplit Carets 


Because of character reordering, ambiguities occur when mapping between text offsets (or 
insertion points) and the visual location of text offsets. As a result, the user must sometimes be 
presented with multiple carets. Specifically two carets are needed for right-to-left and for Indic 
scripts. Figure 10 shows by example why multiple carets are needed for right-to-left scripts. For 
right-to-left scripts the split carets can suggest where the next left-to-right or right-to-left 
character will appear. 
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Multiple Caret Example 


Assume that when a user types ABCD it appears as DCBA. Also assume that 
when a user types 1234 it appears as 1234. Now assume that the user types 
ABC234 and it appears as CBA234. 


fA|B{[c[2[3]4] | Order in which characters are typed. 


‘which characters appear 


so the user 


. the left side of the '2'. Where should go? That depends 
earkosipas typed. A 'D', typed before tt ppear to the left 
L...wil olution | is to 


>t 


Figure A-14 


Because the concept of multiple carets is complicated, an alternate description of the need for 
multiple carets follows: 


While displaying a line of text, characters/glyphs get sorted into visual positions. In some 

scripts, this sorting causes the visual order to have little relation to the “typed-in” order. In 
others words, characters can get scrambled around on the screen when you type, however 
the system remembers the order in which they were typed. 


A text offset points “between” characters in their backing (or typed-in) order. For example: In 
the word ‘Hello’, the text offset of 1 is between the ‘H’ and ’e’. When displaying a caret in this 
case, only one caret appears between the ‘H’ and ‘e’. Split carets occur when characters that 
were typed-in next to each other get visually reordered relative to each other when 
displayed. So for example, if the word ‘Hello’ displays as ‘eHllo’, one caret will appear before 
the ‘e’ and one caret will appear after the ‘H’. 
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Glyph Metrics 


Figure 15 gives an overview of the graphic information that should be supplied by the Font 
Manager on a per-glyph basis. Some features in the diagram are only important for certain 
directions of text; the vertical advance width and origin, and the top and bottom optical 
boundaries are used if the run succession indicates vertical text, while the corresponding 
horizontal advance width and origin, and the left and right optical boundaries are only used if 
the run succession indicates horizontal text. Anchor points are only used to place applied marks, 
while the black bounds are only used for heuristic placement of accents when there is insufficient 
anchor point information. | | 


A number of these features are optional: if they are not supplied, then the Font Manager will have 
to make due with the information it has. For example, if the right and left optical boundaries are 

not included, then they should default to the origin and advance width. If the vertical origin and. 
advance width are not: t to the midpoint of the advance wid : 
glyph height respecti 
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T. Dist. Weights 


& 


Optical Bounds 


Black Bounds 


R. Dist. Wei 
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Appendix B — Application Design Requirements 


Line Layout and the base Text Classes carry out the hard part required to make text international 
within an application. However, an application needs to implement a few features to make text 
entirely international. This Appendix lists the minimal requirements an application should 
follow. 


Paragraphs, Tabs, and Rulers. 


Applications need to let users choose a paragraph’s line direction style and applications need to 
handle tabs and rulers according to the line direction. The choices for line direction are: 


Horizontal. 


the hs "DEF 
Line Layout only handle: 


“Text and tabs 
within a vertical line flow from top-to-botton. Successive lines can flow from either left- 
to-right or right-to-left. Rulers and tabs need to behave accordingly. Also, vertical lines 
are almost always top flush. 


Multi-Columns Pages. 


A text-chain is a contiguous stream of text that is part of the same letter, same story or same 
article. Examples include: Traditional word processors where the text that flows between 
columns is in a single chain, page layout programs where the text ina single story is ina single 
chain, and terminal emulators where the text in the log file is in a single chain. 


A text-chain direction determines the placement of columns—for most applications the term 
column direction can be used for text-chain direction. Applications should flow columns across a 
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page from right-to-left if its associated text chain is right-to-left and from top-to-bottom on a page 
if its associated text chain is top-to-bottom. 


A text-chain direction can also limit a user’s choice of a paragraph’s line direction. For example 
an application likely wants to deal with only horizontal paragraphs in a horizontal chain and 
only vertical paragraphs in a vertical chain. A text-chain may simultaneously contain paragraphs 
with right-to-left and left-to-right line direction settings. A single text chain usually does not 
contain both horizontal and vertical lines. 


An application with a single column may not need a text-chain direction, but still might want one 
to use for defaulting a paragraph’s line direction and flushness. 


Documents and Page Numbers. 


s from front to back or back to.fré 


Applications need to | 
: er side. This flexibility i: 


placement of page nur 


Finally, an appli ot 
visually aligned—see Appen 


ew T-ae 
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Appendix C — Unsatisfied External Requirements 
This section lists the areas of the system that depend upon Line Layout, or that Line Layout 


depends upon which are currently undefined. Until these areas are defined and implemented the 
promiss of Line Layout will not be fulfilled. : 


Font Architecture 


The entire font mechanism is missing. Below I’ve listed only the most critical missing portions 
related to Line Layout. 


Missing Fonts and Missing end ceed 


when a specific font is missing. Ho 
good match is when tw diffe 
fanism to find a font tha: well with a 


example we eannot fornia Japanese = 3 
glyphs. It is very important to get an impl 
of Japanese oe the system. This testi 


Line Layout provides functionality but it lacks user interface. The u 


is application-specific, but we need to provide a standard presentation of the style information 
used to control Line Layout. 


Additionally, we need to investigate the use of contiguous selection of bi-directional text—see the 
section on highlighting. The implications of contiguous selection is not well understood. We need 
to look specifically at cutting text, copying text, pasting text, searching text, and replacing text. 


Passing Application specific text styles 


How should the system handle styled text where some styles may not be understood by other 
systems? This is the same problem occurs when passing any object to another system. Because we 
do not pass the methods that operated on the object with the object, we may not know how to use 
an object. We need a set of standard rules for dealing with unknown objects. 
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Validation of Line Breaks by an Editor 


Applications must be sensitive to configuration changes that can force the recomputation of line 
breaks. For example, font defaults that may differ from system to system will often cause 
different line breaks for a single document displayed on two different systems. This will usually 
result in the document paginating differently on both systems. For some users the new line 
breaks can be unacceptable and an application might have to query a user for advice. 


It is worse than described above because many things can affect line breaks. A wide range of 


In the case of forward 
the ‘width’ of the refe 
line to rebreak and as 


mn and whenthe width is kno cause a 
1e reference change agat 


anism also will need to address this issue— 
nes configured differently, how can we pF 
iti ig? Can it be done and if not how cat 


The collaboration m 
example, on two m 
document for share 


We need an archi with these problems an reed | 
standard user int trol what to d¢ aL 


Bn 
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Appendix D — Open Architectural Issues 


Styles 


Many standard text styles are undefined. These undefined styles fall into two classes: 


The first class of styles are those where the lower level system architecture required to define 
‘algorithmic’ styles do not exist. This set of styles includes graphic and font styles like outline - 
and bold. Currently the interface into the graphic and font system for these styles have not been 
defined. Line Layout will support these styles as soon as they are defined and as soon as the 
methods for selecting the styles are define. 


The second class of styles are those styles where we have not had the time to get around to 


For example, it would be nice if ¥ 
subclassing an adornment style. We 
do. If we have the time to generalize a 


‘we have an 
mechanism that works. 


measurement t 
pieces, does not a . One reason the algorithm fails is that the 
mapping indirectly depends on the characters that are on the line. 


Also, an application, using an incremental line break algorithm, cannot compute the glyphs 
which may overhang a line at a particular break point. Glyphs that can overhang include 
punctuation and trimmed white space. The reason the incremental algorithm can’t work is that it 
assumes glyphs are laid in the same direction as the characters in the text backing. This is not 
true, and as a result line end calculations may be made using the wrong glyphs. 


Finally, hyphenation of words can cause character metric changes and in certain languages cause 
spelling changes. For example, take the word ‘office’. The ‘ffi’ might ligate into a single glyph. If 
we break the word into two pieces, like between the two f's because of hyphenation, the width of 
the two pieces (ignoring the width of the hyphen) may not equal the width of the whole word! 


In most cases, even with these failures of an incremental algorithm, the line breaks computed by 
an application will be close enough. This is because an error will usually cause an application’s 


@ Registered / Restricted Line Layout March 15, 1990 2.7.3-38 


calculation to be off by a small amount and the error will usually be on the side of creating 
shorter rather than longer lines. 


To compute an accurate break point, an application must recompute an entire line for each 
possible break point and pick the line with the ‘best’ width. The problem with this approach is 
that this is slow: Currently we do not have a fast and accurate algorithm to solve the problem. 
More importantly, if we did have a faster algorithm it is not clear how it will affect ZZText’s 
Knuthian line breaking algorithm. 


Finally Line Layout currently does not handle soft hyphens at the ends of lines. It lets a font 
choose to display hyphens or not. Line Layout needs to directly handle hyphens. Line Layout 
must convert soft hyphens to real Unicode hyphens—or NULL Unicode characters depending on 
context—before a Unicode to glyph mapping and before character reordering and rearrangement. 


e line breaks using a 
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Psycho Killer is the nanare oyect for Pink. This docume ses you need to 
manage data on 
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Introduction 


The Psycho Killer project provides classes which aid in the management of data in the Pink world. 
Transactions and logging will be fully supported when the Credence classes are available. 


Architectural Overview 


Psycho Killer provides classes which aid in the management of disk based data in the Pink world. 
Classes are provided for managing objects on disk (like the Chunk Manager) and for finding (indexing) 
those objects. Psycho Killer will use the Credence classes to support transactions and logging. 


Psycho Killer provides classes which associate a key with a value. In this respect, all of the classes 
resemble the TDictionary class found in the Utility Classes. The simplest of these classes associates a 
fixed-key with an arbitrary (heterogeneous) value. For example, a class roughly equivalent to the Chunk 
Manager would return handles.from-requests:to-store-arbitrary data on the disk. These handles: 

used to retrieve the data at 4 : 
one-to-one correspondan¢ 
comfortable dealing wit 
will always take at most 


s classes for associating arbitrary (homogené 
(heterogeneous) values, Once again, the interface for this kind of c 
obviously no direct mappin: b 
this, some type of in f release of pink will include 
atleast one kind of cl é ¢ : i 
class will impleme 
keys. They allow f 
enumeration of th 
indexing technology to explore 
class. 


While the indexing classes will allow you to 43 
advantages to associating arbitrary keys to fixe 
Chunk Manager. First, using a level of indirec 
can be valuable i applications. Second, 
reorganization a 
bucket to bucket 


document uses a d 
manager for managing the 
however, a usefull class, TDiskDictionary, is spresented: 


Classes 


TDiskDictionary! 


A TDiskDictionary is used for the storage of objects on the disk. It works likea TDictionary. You 
can have arbitrary keys and arbitrary values. Objects which are placed in disk dictionaries should 


override the IsEqual() method and the Hash() method.? The interface presented here was meant as 


1. For all the algorithm widget heads out there, a TDiskDictionary uses a directoryless dynamic 
hash table for its index. It also uses a spiral storage scheme to improve the utilization of all of 
_ the buckets and cut down on overflow buckets. 
2. It is very important that your Hash() method returns hash values which are uniformly 
distributed over the values that can be represented in a long. If your hash function does not 
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an approachable (working) first version. 


class TDiskDictionary : public MCollectible { 


public: 
TDiskDictionary(char* fileName) ; 
virtual TDiskDictionary(); 
virtual void Add (MCollectible* key, MCollectible* value, 
Boolean replace=TRUE) ; 
virtual Boolean Remove (const MCollectible& key); 
virtual Boolean Member (const MCollectible& key) const; 7 
virtual MCollectible* Retrieve(const MCollectible& key) const; 
virtual void Commit () ; 
virtual Titerator* Iterator(); 
virtual void SetDestroyFileOnDelete (Boolean doIt 


bs 


TDiskDictionary: :TB 


BD ilename) 
Create anew TDiskDi 


TDiskDictionary: 
Delete the TDiskDict 
operations are lost. Th 


yiskDictionary () 
nary object from memory. Close the ass¢ 
sseciated disk files are only deleted if th 


yn disk. Uncommitted 
= on delete flag is set. 


void TDiskDictz# 


ble* key, MG 


Add a key, value 
equal” to the passed it 
equal” to the passed in key then reptas 
then add the key, value pair regardless 


Boolean TDiskDictionary: :Remove(c 
Remove the key (and its associated value) fro 
in the dictionary 


Boolean TDi 
Return TRUE if 


MCollectible* TDiskDictio: Retrieve(const MCollectibis 
Retrieve a record from the disk dictionary using the passed-in key. Return the 


key or NIL if no value is found. 


e associated with this 


void TDiskDictionary: :Commit () 
Commit all changes since the last Commit operation to the disk dictionary. 


void TDiskDictionary: :SetDestroyFileOnDelete (Boolean doIt = FALSE) 

Normally, deleting the disk dictionary object in memory does not actually destroy the data on the disk. 
Setting the destroy file on delete flag will cause the disk files to be deleted. This routine is not 
implemented for d11. 


Titerator* TDiskDictionary: :Iterator() 
Return an iterator for iterating over all of the objects in the disk dictionary. The values returned from the 


currently do that, a simple technique is to use the result of your existing hash method as a seed 
to a TRandomNumberGenerator and grab the next random number. 
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iterator’s Next () & First () routine are TAssocs where thekey, value pairin the TAssoc 
corresponds to the key, value pair in the disk dictionary. This routine is not implemented for d11. 


Example Code 
This is some example code for adding key, value pairs to the disk dictionary and querying the disk 
dictionary for the values. 


sampleroutine() 

{ : 
// Create a new disk dictionary. 
TDiskDictionary* myDictionary = new TDiskDictionary ("“arndb") ; 


TCollectibleLong keyl1(11); 
TCollectibleLong 


TCollectibleLon 
TCollectibleLon 


TCollectibleLo 
TCollectibleLo 


y 
value3 (102456); 


, 


> disk dictionary 
myDictionar 4 
myDictionar 
myDictionaxrs 


// Commit the changes 
myDictionary->Commit (); 


// Delete the object in memory 
delete myDictionary; 


// ...Sott 
ary ("arndb") ; 
// Checking to see if various keys are in the dictionary. 
Boolean found = myDictionary->Member (TCollectibleLong(11)); 

qprintf("1ll was found as a key in the dictionary = %d\n", found); 


found = myDictionary->Member (TCollectibleLong(1001)); 
qprintf("1001 was found as a key in the dictionary = %@d\n", found); 


found = myDictionary->Member (TCollectibleLong(5)); 
qprintf("5 was found as a key in the dictionary = %d\n", found); 


found = myDictionary->Member (TCollectibleLong(69)); 
qprintf("69 was found as a key in the dictionary = d\n", found); 


// Retrieving a value given a key 
TCollectibleLong* someLong = (TCollectibleLong*) 
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myDictionary~->Retrieve (TCollectibleLong(11l)); 
qprintf ("Value associated with 11 is: %d\n", someLong->GetValue()); 
delete someLong; 


someLong = (TCollectibleLong*) 
myDictionary-—>Retrieve (TCollectibleLong(75)); 
qprintf ("Value associated with 75 is: %d\n", someLong->GetValue()); 


delete someLong; 
delete myDictionary; 
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Introduction 


Pluto is the file management software for the Pink system. This document presents a discussion 
of the architecture of Pluto, and of the capabilities that Pluto affords to its'clients. 


Goals 


The goals of the Pluto architecture are to support the functional requirements of the Pink system 
with respect to file management, and at the same time to maintain a high degree of reliability 
and a high level of performance. Pink is a highly-leveraged, integrated software system, in 
which, in order to deliver the best experience to the user, all of the components must work 
together well. Functionality and reliability requirements are often at odds with performance 


requirements; SO many { @ to be made to achieve a satisfa 


balance. 


Support Pink 


The Pluto services ai 


tended to meet the needs of the Pink Tog 
application progr 


principal clients of Pluto are th 


metre Pluto and the Des 
kept accurate. The Experimental 


Bluto Server. The Pink Personal AppleShare service [5] will implement one example of 
a Remote File System Agent, a software component that offers file service from the 
local machine to a network. Remote File System Agents rely on Pluto for local file 
service, which they then export to their network. 


High Degree of Reliability 


The file systems available under Pluto will implement their on-disk structures so that they are 
recoverable; that is, so that they can be reverted to an earlier consistent state in the event of an 
unexpected failure. There will be no need for a separate scavenging utility, like Disk First Aid. 
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High Level of Performance 


Pluto provides various classes of service intended to deliver performance to different kinds of 
clients. Control over file system policies, like those for disk space allocation and data 
buffering, is made available through the client interface, for those clients that reject the 
default policies. 


Heterogeneous File Systems 


The greatest functional requirement of the Pink system is the need to support a mix of 
heterogeneous file systems. Media written by other file systems, and network file service 
offered by other systems, can be imported into the Pink System through the Pluto guest file 
system facility. The heterogeneity of guest file systems is masked for basic file system 
operations, so that all fi en it comes to storing documents.a: 
applications. Be 


Overview 


The architecture 0 
team, acting on th 
some service to 
through interpre 
is based on theS 


‘uto is based on the client-server model. 
; e human user of the compu 


program, an Opus/2 
er is a team providing 


is a set of classes for file system objects. 
real objects ee bya local server kno§ 


between client and server. 
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Application — 
Application performs operation 
on a surrogate object 


volume.Flush (} 


Interface layer translates 

operation into a system-level . 
request to the appropriate File 

System Server 


Pluto Interface 


fssClient.FlushVolume (whichVolume) 
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Message-based : 


Client 
Application 


ene cene cera acsratecsacaerssneretesevsteratacecerelotacsne arsterscetetareteverepe ta sareete tee" 


Figure 2. Relationship Between Client and File System Server 


The Pluto Interface is designed for the file systems of the next decade; all file sizes and offsets 
are expressed in 64-bit quantities, allowing for a maximum size of 18 billion gigabytes, and all 
symbolic names are expressed using Unicode [7], the international 16-bit character set. The 
interface also makes regular use of the polymorphism of objects to build in extensibility. For 
example, lock types are expressed as objects, allowing for a new file system to introduce a new 
type of lock without necessitating a change in the interface. 
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The salient concepts supported in the Pluto Interface are file system objects (volumes, 
directories, file groups, files, and reference files); access control; logical names; user-defined 
properties; property queries; memory-mapped and byte-stream access methods; file-level and 
record-level locking; and user-defined file Content Servers. 


Adapters 


Opus/2 is a system kernel on which different operating system environments can be constructed. 
The software that implements a particular operating system environment is known as an - 
Adapter. As far as the file system is concerned, the role of the Adapter is to “adapt” the Pluto 
Interface to the host interface of the operating system environment. Figure 3 depicts a foreign 
program obtaining file service through an Adapter. 


Application pe 
using inter 
system 


plication 


error = Flu volrefnum) 


volume .Flush () 


| 
| 
: 
g 
: 


Message-based request 


Figure 3. Relationship Between Application, Adapter, and Pluto Interface 
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File System Server 


A File System Server is responsible for managing a set of volumes of a homogeneous format, for 
example, a set of HFS volumes or a set of High Sierra File System volumes: A File System 
Server is an implementation of a particular file system, and, hence, by having different servers 
available in the system, different file systems are supported simultaneously. This situation ts 
depicted in Figure 4. 


Client Application / 


ir.GetIterator () 


ile.GetDataSize () 


Y 


Pluto Interface 


Figure 4. Application Using Multiple File Systems 
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Each File System Server is responsible for delivering a standard set of services. This set of 
services is defined by the Pluto Interface. In this light, each File System Server can be thought 
of as an adapter that adapts the services of the specific file system to the services described by 
the Pluto Interface. This scheme accommodates both local and remote file access. A File 
System Server for local volumes, that is, volumes on devices directly attached to the computer, 
will express each Pluto operation in terms of the on-disk structures of the specific file system, 
whereas a File System Server for a remote volume will express each Pluto operation in terms of 
the network protocol used to communicate with the network file server. 


Any File System Server is free to implement second-tier operations in addition to the standard 
operations of the Pluto Interface. Second-tier operations are made available to client programs 
by introducing subclasses of existing classes in the Pluto Interface. 


Some examples of local file systems are HFS, MFS, ProDOS, High Sierra, MS-DOS, OS/2 
HPFS, and A/UX, while some examples of remote file systems are AppleShare, PC-NET 
(SMB), TOPS, Novell: 


st also provide low- 
of the File System 
nts a set of file 
Memory 


Server known as 
allocation and di 
Manager of the 


Ona file-by-fil 
user-supplied Content Se 
semantics, so that two identica 
the same data, but is otherwise free té 
to the kernel. 


anslate, 


Pluto File System 


support the Pluto Interface. These new file systems will be the native file systems for Pink 
machines, and, because they support the Pluto Interface directly, will afford the best 
performance and reliability of any file systems available for the Pink system. 


Guest File Systems 


File systems other than the native file systems are referred to as guest file systems. Guest file 
systems support volumes created by non-Pink host machines. Such volumes are referred to as 
guest volumes. The on-disk structures of a guest volume may not be capable of directly storing 
certain information necessary to support the Pluto Interface. When this happens, the 
information must be stored in a meta-structure, like a file. This file contains whatever 
additional file system information is necessary to make the guest file system look like a native 
Pluto file system, and is referred to as the Pluto Database. 
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The discussion so far has related to the on-disk data structures of a local file system, but the 
same line of reasoning can be followed with respect to remote file systems. When there is no 
direct support in a remote file system’s protocol for the storage of a particular piece of 
information, that information must be stored in a Pluto Database on the remote volume. 


Since the Pluto Database is accessed using client-level mechanisms, the integrity of the 
database is difficult to guarantee. Apart from the obvious data-loss problem should the 
database file be overwritten or expunged, there is also the problem of consistency to consider; 
whenever a guest volume is shared with non-Pink systems, the information stored in the Pluto 
Database can become inconsistent with the actual state of the volume. - 


Various implementation techniques can be brought to bear to improve reliability, like on-the- 
fly consistency checking and replication of the information in the database, but they all impose 
a penalty on the overall performance of the file system. Each guest file system implements a 
file model for the benefit of its clients, and the logical distance from that file model to the 
Pluto model determin 


Remote file systems p 


the sharing of code and implementation 
the construction of such servers. The co 


Customers can integrate a Pink machine into their pre-existing distributed and network file 
systems once a File System Server has been developed for their file system. 


Pluto supports an import-export, or remote-mount, model of remote file access. Volumes can be 
imported individually from remote file systems that export a collection of directory trees, like 
TOPS and RFS. Distributed file systems, like Sprite, that implement a network-global 
directory tree can be imported as a single volume. 


Directory trees can be exported from the local machine to a network with the help of a Remote 
File System Agent for that network. The Agent represents remote clients who wish to access 
file system resources on the local machine. Remote File System Agents are clients of Pluto, and 
are not, therefore, a part of the Pluto architecture; however, they rely heavily on Pluto 
services. : 
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The import-export model allows the user to explicitly control the nature and the extent of file 
sharing, and to control the consumption of local resources. 


Volumes on the Desktop 


From the user’s perspective, the desktop is populated with objects that can be opened through 
direct manipulation. One object might be a local volume, which can be opened to reveal the file 
system objects in the root directory. Another object might be an AppleTalk network or an NFS 
network, either of which could be opened to reveal the next semantic level (zones in the case of 
AppleTalk and domains in the case of NFS). Authentication might be required when a 
protected object is opened, for example, opening an AppleShare server would require 
authentication before the volumes within it could be viewed. Whether the user has to type a 
password at that moment is determined by the policy for caching authentication information 
locally. 


Local volumes are di 
executing, they regi 
or the Access Mana 


ishes a connection so 
-d. The mount call returns a volume object 


Pluto will cycle ¢ 
system image w. 
exception is rails 
media has been 
circularity; an‘Acce: 
File System Server, unless 
or in a boot image. 


Remote volumes are discovered by bro 
desktop objects representing zones and fi 
the point that a volume to be mounted h 
network file holding the volume oc 
s uires the establish 


of Pluto. 
along with’ 


A volume mount y fail because of access control restrictio ed with the 
volume itself; for example, if the volume is protected by a password. Such a failure will raise 
an exception to be handled by the software trying the mount operation. 


File System Objects 


Surrogate Objects 


Most of the file system objects defined by the Pluto Interface classes are surrogate objects. A file 
object held by a client, for example, is a surrogate for the real file stored on disk. A surrogate 
object is a description of the real object, used to identify the real object to other system functions. 
Holding a surrogate object is the equivalent of holding a name. When the real object is deleted, 
the surrogate object will be invalidated, and operations performed against it will fail. 
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Volumes | 


A volume object (TVolume) represents a mounted volume. Volume objects are acquired by 
interacting with a seminal object (TFileSystem) that represents the total file system (i.e., the 
ageregate of File System Servers). The seminal object can return volume objects in three ways. 
First, in exchange for a mount descriptor object (TMountDescriptor). A mount descriptor 
encapsulates the file-system-dependent information necessary to establish a connection to a 
volume. The mount descriptor might contain information like a password object, an object 
representing the storage provider (e.g., local device or network session), or a file system type 
object (e.g., NFS or AppleShare). Second, in exchange for a volume name. Third, indirectly 
through a volume iterator, which can be used to obtain a surrogate object for each mounted 
volume. 


A volume object can be:asked:to:returmasurrogate object for its root directory. Starting.a 
root directory, client erarchy of directories on th 


Local Volume 


3cal machine. The 
: System Server; the 
lemented by a device 


A local volume is r 
file system volum: 


orded on some block-storage device attache 
sen b clients i is an abstraction implement 
a logical volume ab 


A logical voluny 
level addressing’ of 
partition on a physical vol 
logical volume may be a stable - volur 
Access Manager hides the exact imple 
can, however, return a geometry object t 
underlying physical volumes. 


feature will ni sd fOr the first release of Pluto, th 


Directories 


Every volume stores a hierarchy of directories. File system objects stored within the hierarchy 
of directories can be discovered by searching from a given directory; the directory object is asked 
to look up the object based on a symbolic path name relative to itself. If the object is located, a 
surrogate for it is returned. A description of symbolic path name objects can be found in the 
section on Naming. 


A directory object can supply an iterator that will enumerate the file system objects contained 
in the directory. Using a property expression as a filter, the iteration can be set up so that only 
objects of interest are returned (see the discussion of Properties). 
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File Groups © 


A file group is a directory subtree rooted at a distinguished directory known as the parent of the 
file group. A file group affords a tighter bundling of file system objects than can be achieved 
using the normal directory mechanism, and is intended to represent a single entity to the file 
system client. For example, the access control list of the file group parent overrides the access 
control lists associated with any of the file system objects in the group. 


File groups can be nested; the interior file groups are considered to be part of the outermost file - 
group until they are extracted. Any member of a file group can return a surrogate object for the 
parent of the file group. The file group parent can be asked to return information about the file 
group itself, like its aggregate size. Operations like these will be very fast in the Pluto File 
System, but will be more expensive on guest file systems (e.g., computing the size of a file group 
might require traversin 


n-fork files are used in the Maé 
ybounded number, and each 
e; for example, a me és 


File groups will be us¢ 
except that instead of 
type of file system ob 
reference file (symbé 


fit can be any 
ie group can bea 


secondary storageé: 
created from a surrogate fi 
like data transfer, space allocatio 
connection to the file, so that deletion’s! 
causes the associated file to become closed 
referring to the same file (also, if the file h 
the segment is taken down). 


capability for access to the file. For local file systems, changes in the access control information 
associated with a file will not revoke existing file handles. Remote File System Agents may 
want to recheck permissions on every access; so this behavior may be provided as an attribute of 
a handle. 
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Shared multiple readers and multiple writers read-write; deny none 


Exclusive Read single reader read; deny read-write 


Exclusive Write read-write; deny read-write 


single writer 


Protected Read multiple readers or one writer read; deny write 


Protected Write read-write; deny write 


multiple readers and one writer 


sevel Locks 


rr. If a team 


A file handle is asso¢ ‘reates it by the File Syst 


share file handles. 


Another type of £ 


taken that a glot 
cooperating te 
Credence software could use this 
file handle cannot be passed across 
be counting is a question currently being'¢ 


Temporary Files 


emporary files 


another (e.g., from ¢ linker). The secondary storage associates 
is reclaimed when the system restarts. 


Various performance optimizations are made for temporary files. Since temporary files are not 
permanent, storage allocation and data write-back are performed in a lazy manner, in the 
hopes that the file will be destroyed before the actual work must take place. In addition, 
when temporary files are allocated in a sparse manner, the file allocation on disk is actually 
done sequentially, relying on the virtual memory page tables to preserve the correct order of the 
file pages. This strategy greatly reduces the cost of sparse temporary files on guest volumes 

that do not support sparse files. Sparse temporary files will become more common once the 
Opus/2 kernel begins to make use of copy-on-write segments. 


* . : : . * 
A close-and-delete operation allows the same optimization to be made for permanent files. 
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Immutable Files 


A file can be made immutable; once this is done, the file can never again be written. An 
immutable file can be read (copied) or deleted. 


Reference Files 


A reference file is a file system object that is actually a reference to another file systern object> 
Reference files are used by the Pluto File System to implement symbolic links. Reference files, 
as a general mechanism, can be used to implement other kinds of references, like auto-mount 
points that are references to remote volumes, or "caching" references to remote files that, when 
opened, copy a version of the remote file onto a local disk. 


Reference files introdueé 
by a File System Servs 
individual File Syste 


inds of reference files me! ove is up to 


volumes that can be mounted. This mod: 
backbone of a distributed time-sharing s\ 
user to sit down at any computer and acc 


th through the hierarchy of d or er volume, 
. Path names are always interprete 
volume and directory; volume names do not appear in path names. Path names are represented 
as an array of textual strings. Adapters are responsible for parsing host path names into this 
canonical form. A distinguished entry is used in the canonical path name to indicate the 
immediate parent directory. 


Adapters can participate in path name interpretation by performing separate directory look-up 
operations on each component of a path name, rather than passing the entire path name to the 
File System Server for interpretation. The UNIX Adapter would do this for programs that 
have set their root directories to something other than the global root directory. 
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Path name interpretation is typically performed once in order to acquire a surrogate object, and 
then further operations are expressed in terms of the surrogate object. Since path name 
interpretation is not performed on every operation, verification of the access permissions on 
ancestor directories is also not performed. This is usually acceptable, but if a local file system 
is being exported by a Remote File System Agent, such bypassing of directory-level access 
control might not be tolerable. Whether path access permissions are checked for every 
operation on a surrogate file system object should be an attribute of the object. 


Pluto does not support the notion of a working directory. Clients can acquire and hold surrogate 
objects for any directories of interest. ‘ 


Add Names 


file system object in a particular direc 
system object, except that all al 


Additional names can 
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directory are taken fr 
minimal names for fil 
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To address this problem, Pluto provides: 
for a file system object. The logical namé 
object's symbolic name. A logical name is < 
assigned by clients. 


name will 
performance, but: for the correct operation of the n 
the low-level identifier supplied by the host file system implementing the named object. 


Logical names will be cheap in the Pluto File System, but supporting them in guest file systems 
will be more expensive. For this reason, every file system object is not created with a logical 
name. A logical name for an object must be constructed explicitly. A file system object can have 
at most one logical name at any given time. 


File Logical Names 


The logical name of a file or directory can be used to uniquely identify that object in the context 
of a volume. A globally unique identifier for a file or directory can be constructed by combining. 
its logical name with the logical name of the volume on which it is stored. Note that such an 
identifier does not support migration of the file or directory away from its home volume. 
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Volume Logical Names 


The logical name of a volume encapsulates a file system identifier that selects the File System 
Server for the volume. A volume can be found based on its logical name; Bluto will extend this 
search capability over the network. 


Properties 


A property is a named, typed value associated with a file system object. The value of a 
property can have a built-in type or a class type. All file system objects have member functions 
(MFileSystemProperties) to retrieve and set the values of properties associated with them. 
Properties are named using textual strings. Since all properties are typed, an exception i: is Eaised 
whenever there is a t besresolved with a conversion. A set ; 
can be named in a lis. t can be used to retrieve or se 
in one operation; th n used in conjunction wi 
. iterator. 


Property Expressions 


Such simple predicates can be strung: 
expressions like the following: 


file server). The number-of:contex see between client and server is then minimized. 


Note that some queries will be very expensive to process; however, if a query can be optimized, 
the File System Server has the best advantage. 


System-Defined Properties 


System-defined properties are those properties of file system objects known to the managing 
File System Server. These properties are generally stored in the on-disk structure of the file 
system. There is a mandatory set of system-defined properties that all File pystem Servers 
must support. 
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When a file system object is copied across heterogeneous volumes, it is often desirable to 
preserve the system-defined properties of the originating file system. Pluto supports this by 
maintaining a per-volume lightweight database of properties. The size of an individual 
property will be limited (less than two kilobytes), allowing for optimizations in the access 
method implementation. 


The system-defined property database is also used to make existing on-disk structures 
extensible, since new attributes can be added at any time. 


User-Defined Properties 


Utilizing the same mechanism, Pluto allows clients of the file system to assign new properties 
to file system objects. These user-defined properties can be used to hold any kind of information 
about the object; howe if al i f information is to be stored in association with.a.-.. 

file, the file group mec 


If a user-defined pro 


property expressions on r volume, 
then the volume can: 


elerate those queri 


Protection 


Policy 


The protectio 


File Service Domain 


When discussing protection across heterogeneous file systems, it is convenient to introduce the 
concept of a File Service Domain, an autonomous administrative environment with its own 
implementation of file service, name service (for exported resources), and authentication 
service. An AppleShare File Server is a good example of a File Service Domain, as it 
implements its own authentication database (containing user, group, and password information) 
and naming database (containing information about exported directories). Another example 
would be an NFS network in which a Yellow Pages name service provides a common 
authentication database and naming database. 


* « * « « . . 
- “ Similar behavior is anticipated when A/UX volumes are mounted under the Blue Macintosh operating 
system. 
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Authentication 


In order to access resources in a particular File Service Domain, a client must be authenticated in 
that domain. Authentication is the process of ensuring that a client is authentic, and should 
therefore be granted the access rights associated with its identity. Authentication is based on 
the client’s ability to produce information proving its identity, and on the server's ability to 
determine that the information presented has not been forged. The information supplied by a 
client is referred to as its credentials. Credentials are ultimately tied to some human user who 
has, at some point, demonstrated his own identity, usually by tendering a password (though ~ 
other mechanisms can be employed, like magnetic card keys). Credentials contain, at a 
minimum, a unique identifier for the user within the domain in question. 


The user will identify himself to the File Service Domain containing the resources in which he 
- is interested. If the File Service. Domain.is.implemented by a single server, then the unique:user 
ver. If the File Service nee it : 


servers, then the use 
Service Domain, and: 
Authentication Se 
database, and grants 


aid local credentials 
yer across a machine 


are mapped into: 
boundary. In eit! 
overall level of. 


Regardless of the'seo 
them, like an expiration tim 
affiliations of the user. 


er an insecure network; 
return credential: “for presentation to a particu 
involves protecting the’c entials, generally by encrypting them with a éy known only to the 
Authentication Server and the server to be contacted (the server’s private key). In this way, 
the server presented with a set of credentials can determine if they were issued by the trusted 
Authentication Server. When a client requests credentials for a particular server, the reply 
from the Authentication Server is encrypted using the client’s private key; so only the client 
can extract the credentials from the reply. The client’s private key is a reduced form of the 
password supplied by the user. The reply contains another encryption key, the session key, 
which can be used for secure communication once the session between the client and server has 
been established. The session key is replicated in the credentials, so that it can be safely 
passed along to the server. To prevent replay of captured credentials, and to authenticate the 
client, the server can issue challenges that require the client to demonstrate knowledge of the 
shared session key. 
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The scheme just described relies on conventional encryption, using a single private key. A 
similar level of protection can be provided by schemes that use public-key encryption, where 
public keys are used to encrypt messages sent to clients or servers that can decipher them using a 
private key. 


Local Authentication 


When credentials are to be communicated only within the bounds of a single machine, they can 
be safeguarded by the operating system kernel, relying on the hardware protection boundary - 
implemented by the user-supervisor trap mechanism. This obviously works when the file 
system is implemented as a part of the kernel. When the file system is implemented outside of 
the kernel, the IPC service provided by the kernel must be made secure. This can be done by 
having the kernel fe messages with an pied ear identifier, from which the user on 


collect the user’s passi 
executing on behalf | 
the Pink system that. 
identity of a client 


Partitioned / 


Before turning t 
local authentics 
personal compu 
membership in a File Se 
user-group database, but they store"p: 
whether, or how, to honor protection 
from its File Service Domain. For examp 
Domain relies on the network authentica 
unavailable. When this happens, the al 


unknown and cannot be authenticated. If normal, oe access is to be enforced, the volume 
itself must contain the necessary authentication information. In this case, the volume 
implements its own degenerate File Service Domain. 


The area of authentication, and the Local Authentication Service in particular, is one where 
more design work is necessary for the Pink system. Human interface concerns will, no doubt, 
guide this work. The Pluto architecture provides mechanisms that are general enough to 
accommodate whatever system design is adopted. 


“? Registered / Restricted Pluto . March 15, 1990 2.8.2-19 


Authentication for Remote File Access 


Remote file access requires authentication between the File System Server, as an agent of the 
client, and a Network File Server. Remember that, for connection-based network file servers, a 
preestablished session is handed off to the File System Server. If this session is not 
multiplexed across multiple clients, then credentials are implicit in the session (this is the case 
for AFP). If the session is multiplexed, that is, it has been established from machine-to- 
machine rather than from client-to-server, then credentials must be associated with each client 
sharing the session (this is the case for RFS). If the network file server is datagram- or RPC- - 
based, then credentials must accompany every rendezvous. 


The credentials for clients accessing remote file systems should come from the Local 

Authentication Service. If multiple users can be represented by teams executing concurrently, 
then credentials must be grouped by user. A client team executing on the behalf of a eben 
user, and attempting ‘ile Service Domain to another, mu se 
credentials for each 
result in guest acce 
from one File Serv 


ip redentials 


Whether a File Sys i i ‘ f ication Service or 
gets them directl are opaque to Pluto; 
they come as the File Service Domain, 

and might affore¢ .0 [9] relied on 
authentication i t 
over the netw@ 
fabrication bys: 
System Server does not offer a y 
network file system it represents. 


For communication with network file ser 
multiple sessions must be handled by a - 
simultaneously 
session is t 


Access 


From the point of view of Pluto, the credentials do not so much identify the client as they 
identify the client’s title to a particular set of access permissions. A permission is the right to 
perform a particular operation on a file system object. In Pluto, an individual permission is 
represented by an object. Permission objects can be collected together into a set of permissions 
(TPermissionSet). A set of permissions can be associated with a principal, which is an object 
that represents an accountable entity, like a user or a group of users. A list of (principal, 
permission set) tuples can describe the access allowed to a particular file system object, and is 
called an access control list. 


Access Control List 
The Pluto Interface permits an access control list to be associated with any file system object. 


Individual File System Servers may impose greater restrictions; for example, the Pluto File 
System does not permit access control lists on individual files. 
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A principal object encapsulates a user or group identification that can be tested against the user 
identification in the credentials of a client. For some file systems like NFS or Andrew [10], the 
credential object would contain a list of the groups to which the user belongs. For other file 
systems, the credentials would contain only the user identification, and the Authentication 
Server would need to be consulted for information about group memberships. In the former 
approach, changes in group membership are not apparent until the credentials are invalidated 
or expire. In the latter approach, since protected file operations may require an interaction 
with the Authentication Server, response-time bounds on those operations become hard to 
assess. The nature of credentials for the native Pluto file system, and for the Pink system in 
general, has not yet been determined. This aspect also has an effect on the human interface and 
the feel of the system. 


Since a principal named in an access control list is an opaque object, it could be a key ora 
password as easily as it could be the identifier of a user or group. Any client quoting the 


password would be grant ed sions. Such an approach has been adopte 


file systems may take advanta 
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flexibility. 


An access control list 
permissions are obj 
be reused elsewher: 


sntation, the Pluto acces list classes could 


A File System Server that wishes to be a 
permissions as the local Pluto File Systent, 
semantics. Additionally, the File System 


Pluto Perm 


The permissions defined by the Pluto File System are shown in Figure 6. Remember that the 
Pluto File System does not implement access control at the granularity of an individual file; so 
the file access permissions listed are simply a suggestion to implementors of File System 
Servers. 


The Pluto permissions relate to the current AppleShare permissions as follows: the 
AppleShare see-files and see-folders permissions have been folded together (in practice, they 
are rarely set independently), a new permission has been introduced to control delete and 
rename operations (as suggested in the preliminary ideas published for AFP++ [12]), and a new 
permission has been added to control modification of the access control list itself. 
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This last permission has been included to allow a separation of access control mechanism, as 
reflected in the Pluto Interface, from access control policy. No notion of file or directory 
ownership is visible in the Pluto Interface. The mechanism for access control is a set of 
permissions associated with a principal by way of an access control list. One permission is 
permission to modify the access control information itself. A particular File System Server 
might implement the policy that only one principal, the owner of the protected file system 
object, can have this permission at any one time. Another File System Server might implement 
an ownerless policy, like that of the Andrew file system. 


Likewise, no notion of groups or a primary group is visible in the Pluto Interface. The access 
control list mechanism allows for any number of principals (groups) to have access permissions 
to a particular file system object. Restricting the number of groups, or distinguishing a 
particular group, represents a policy. 


When an ownership policy is in effect, each file or directory would likely have an owner _ 
property associated wi mary group policy is in effect, ea¢ 
directory would hav up property. g 


The access control é System Servers can val change in the 
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Figure 6. Pluto File System Permissions 
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Inhibitory Flags 


Many file systems support inhibitory flags as a supplement to the regular access control 
mechanisms. These flags can be set or cleared by any client with permission to modify the 
properties of the protected object; so, for example, a setting a write-inhibit flag does not afford 
the same degree of protection as withholding general write permission. However, inhibitory 
flags are quite useful in preventing accidents, and in controlling access at a gross level. The 
native Pluto File System will support, at least, write, rename, and delete inhibitory flags on 
all file system objects. 


— of Protection 


ieee, other than truste 
secure. On the other 
rule, cannot be made 
security checks woul 


The security provi 
integrity of the file 
from avoiding ac 
breach the securi 
example, or by i 
debuggers, like © 
once a volume is detached fr 


The Pluto File System implements a 
provide a security envelope that clients 
described, a passive protection mechanis 


sd$'for accessing the da 
mapped into the i f€am and its contents accessed't 
virtual memory addresses. Sec nd, any file can be opened as a stream arid its ntents copied to 
or from the virtual address space of a team through read and write calls against the stream 
object. 


No record- or text-oriented access methods are supported. These can easily be implemented 
through objects that are clients of the Pluto access methods. Similarly, device independence, or 
the ability to perform I/O without knowing the nature of the source or sink of the data (e.g., a 
file on disk, a serial line, or a network session) is implemented at a layer above the Pluto 
Interface. The Pluto access methods deal strictly with files on block-structured devices. 


There are several ways a client can use the two basic access methods provided by Pluto. 


First, a client can map a file into its virtual address space (TSegment) and access the segment 
directly. 
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Second, a client can use the stream operations of the segment object to copy data to and from the 
mapped file. This approach combines the streaming (copy) model of access with the inherent 
efficiency of memory-mapped files for handling small, unaligned data transfers. 


Third, a client can use the stream operations of a Pluto file stream object (TFileStream) to copy 
data to and from a file that is not mapped into its own address space. In this case, the file may 
or may not be buffered by the Opus/2 Virtual Memory Manager, at the discretion of the client. 
Buffering is helpful for servicing small transfers from extremely large files, for which the 
overhead of memory-mapping is too great. To a real-time client attempting to move bulk data 
directly from a file into its own address space, buffering reduces the performance of the transfer. 


Content Server 


The Opus/2 Virtual Memory. Manager.administers real memory as a pool of page frames MOSt: 
of which are backed b ed to permanent or temporary files : 
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Content Server 


Send request for block map of 


: Receive request 
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Disk Access M 


A client can indicate a‘custom Content Server when opening a file, and specify that the server 
will either manage the contents of the file or simply require notification when Content Server 
operations are taking place. The Credence software makes use of the notification service to 
implement its write-ahead log protocol. This relationship is shown in Figure 9. 
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Pluto does not implement a separate logical buffering mechanism for file data, but rather 
cooperates with the Opus/2 Virtual Memory Manager to manage the contents of real memory. 


An open file may have caching enabled or disabled. When caching is disabled, the data of the 
file can be accessed only by using a Pluto stream object. Each read or write request goes to the 
Content Server for the file and the data is moved between the backing storage and the virtual 
memory of the client. When caching is enabled, the data of the file can be accessed through a 
Pluto stream object or by memory-mapping the file. When access is through a Pluto stream 
object, each read or write request generates a system call to the Opus/2 kernel. 


The Opus/2 Virtual Memory Manager maintains a cache directory that describes what data 
from cached open files are present in real memory. The cache is filled by going to the Content 
Server for the file being accessed at the time the cache miss occurs. Cache misses can happen 
because of page faults (memory-mapped access) or because of read requests (stream access); the 
Content Server does not distinguish between these two types of access. 
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The Virtual Memory Manager, because it has dominion over the global cache, can institute 
policies that improve overall system performance, like deferring the copying of data to new 
frames as cache hits accrue to clients reading shared open files (i.e., a copy-on-write strategy). 


Because there is a single shared cache for all file data, the consistency of shared file access is 
maintained for all clients executing on the local machine, regardless of what access method 
they are using. 


Remote Data Access 


Maintaining the consistency of shared file access for clients on different machines is the 
responsibility of each Remote File System Server. The File System Server must implement the 
cache consistency protocol of the particular remote file system that it serves. To this end, the 
Opus/2 kernel provides on the local file cache: 
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Final 


Anyone interested in having a copy of the complete Pluto Interface specification should request 
one from me. I can be reached by AppleLink at "MCFALL" and by QuickMail at “Crimson 
Permanent Assurance Co.:PINKTEAM:Chris McFall." 
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Class Hierarchy of File System Objects 
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Intro duction 


Bluto is Personal AppleShare for Pink. Personal AppleShare allows a Pink user to share files 
with other Pink and non-Pink systems. Bluto will support existing AFP servers and clients, and 
introduce support for Pink file system capabilities. This section presents an overview of Bluto, 
its features, and its place in the Pink file system architecture. 


Goals 


* Pink Personal AppleShare aims to provide transparent remote file system access. 
As such it is a fundamental building block of the Pink system, aiming to provide the 
user with the same experience no matter what file system is being used for storage, 
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Personal AppleShare consists of an AppleShare client and server. Both are Pink teams which 
will always be launched at system startup time. The client packages local file system requests 
into network AFP requests. The server handles network AFP requests, dispatching them to the 
Pink file system. The relationship between the Pink file system and Bluto is shown in figure 1. 


Note that the Pink file system client could send its requests directly across the network to the 
Pink file system server, thus bypassing Bluto. We chose not to follow this design, as use of the 
Bluto client and server allows network performance optimizations to be made on the client side, 
and provides for compatibility with existing clients and servers; allowing remote access to 
heterogeneous systems. 
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Figure 1. The Pink file system and Bluto. 
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file system servers, this mapping will be 
Pluto, the Pink file system. 


The Bluto serv ystem requests from the netwi - 
versions 1.1, 2. 0, and'2.7 will be implemented, thus supporting Blue 6. 0,702 and continuing to 
support the Apple II and AppleShare PC. In addition, AFP k.0 will be introduced. 


The server manages one or more local volumes. Volumes may be local disk volumes, CD-ROM 
volumes, or exported sub-directories. The Bluto server is a client of the Pink file system, 
making use of file system caching, access control, properties, etc. The ability of Bluto to serve 
HFS, High Sierra, etc. is dependent upon Pink support for these file systems. 


It is a goal of the Bluto server to not maintain any parallel data structures. 
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Features 


User Interface 


Both the Bluto client and server require a variety of local services in order to implement 
Personal AppleShare. Among these are interaction with the Pink Finder, the Pink File system, 
the Pink Browser, the Pink Address Book, and the Pink Network Manager. Both Bluto client_ 
and server will also interface with a local authentication service for obtaining and verifying 
remote credentials. To a large degree, these Pink services will determine the user's experience 
of both the network and local file systems; the features that follow help to define the 
requirements of Bluto. 


Bluto has very little hz 
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groups, and access ri 
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Shutdown 


The server will 
activity, tas 


number of § ‘be running to accept 


The user will be'a ver parameters and explicitly enab | sharing froma 
preterences or other such dialog. The latter will not shutdown the server, it will only disable 
sharing. 


Volumes 


The Pink file system is hierarchical, with the topmost level being a collection of volumes. 
Volumes may be physical volumes, such as a hard disk or CD-ROM, or network volumes. Bluto 
allows sharing of a directory sub-tree at any level in the hierarchy as a network volume. All or 
part of a volume can be shared. 


The Pink file system also maintains file system privileges. The act of sharing a volume or sub- 


directory will be integrated with the finder interface. Sharing volumes and directories will be 
identical operations on both the local file system, Pluto, and remote file systems, Bluto. 
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The client will make a distinction between explicitly mounted volumes and volumes mounted 
via links. Auto-mounted volumes will be expired after a period of inactivity. 


We would like to remove the limitations imposed by having AppleShare volumes appear as 
individual icons on the desktop. We expect links and authentication to result in an increase in 
the number of volumes mounted. One possible solution is to permit browsing of volumes and/or 
servers as an extension of directory browsing. 


Accessing a volume through a file link (via desktop object or document link) should be 
completely transparent, with the authentication services performing the necessary user 
verification. Since many volumes may be mounted indirectly through links, we expect that such 
mounts will timeout and unmount after a period of inactivity. This should not result in any 
visual change to the user, and remounting the volume on subsequent activity should be 
transparent. 
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. the latter would be seen as ‘'!Bread ? ??' to a Blue client. 


There is no explicit support (or lack of support) for case-sensitivity. This attribute of file 
naming is server specific. Case-insensitivity is the preferred behavior, and the Bluto server 
will be case-insensitive. 


Users & Authentication 


Users and groups will be managed by the local address book and authentication service. This 
functionality has been separated from AppleShare, since these users, groups, and 
authentication will be used by services other than Bluto. 
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The address book should include a mechanism for accessing users and groups on ADAS, as well 
as allowing the user to create new users and groups which may not be in the ADAS database. 
The Bluto server will use these local users and groups in addition to the ADAS lists when 
checking access rights. | 


The local authentication service will be the system's point of contact with any network 
authentication services, Apple or otherwise. The user may have accounts on systems which do 
not use the authentication server. We would still like to have transparent mounting of these 
volumes, and expect the local authentication service to handle multiple authentication 
domains and storage of passwords. 


The Bluto client and server will use the authentication service to establish authenticated 
sessions. This service should provide, or allow the incorporation of new authentication 
methods: e.g. Kerberos, Apple Random Number Exchange, etc. 


Directory 
S f 


hus Bluto, will support access control lists as 
protecting file system objects. The advantage of access control list are their flexibility: 
directories can be shared with one or more users or groups. This lifts the constraints imposed by 
the protection bitmaps used in Blue. 


Although the local file system will allow support for volumes with file level protection, Bluto 
will continue to provide protection only at the directory level. This ‘protected container’ 
paradigm is easier to work with, as users typically keep a mental map of where their 
files/folders are located, and their protections. Supporting file level protections would greatly 
increase the size of this mental map, making the system more difficult to use. AFP k.0 will 
provide support for file level protection for servers implemented in foreign environments. 


The semantics of users and groups are not defined by Bluto or the file system. The definition 
depends upon where the users and groups are defined — locally, in ADAS, or on a remote third- 
party system. Our goal is for the local and ADAS users and groups to have similar semantics 
(e.g. groups of groups, administration privileges, etc). 
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The rights for file objects are kept on the local file system, by Pluto. 


Existing AFP 2.1 servers are easily presented by the access control list interface. Updating 
these privileges will be inconsistent for the user, since adding of additional shared users and 
groups is not permitted under AFP 2.1. 


Object sharing and access rights should be well integrated with the Pink system. In particular, 
other objects which may have remote accessors (Remote Access, Collaboration, whatever.) 
should use the same permission model and interface. We must also handle the case where a 
foreign file system defines object protection capabilities not supported by the local file system 
or Bluto. There must be a consistent way to extend the access privileges user interface without 
sacrificing the consistency of the user interface. 


Properties 


Bluto will support pr. 
emulated. AFP k.0 


Pink File System. For AFP 2.1; 
t for file properties. g 


Caching 


The performance 
and disk[{Lazo8 
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reduce the CPU 
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ition for the server CPU 
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The protocol to be used by Ap : 
consistency protocol [Nels88]. This a 
system, even when the file is being cache 


Files are distinguished as write-shared 
cached by the.AppleShare client without 


i ctly from the 


When a non-write-shared file is subsequently opened for write, the server initiates a callback 
sequence. Each client which has the file open is notified that the file is open for write, and all 
cached data must be flushed. Clients are notified sequentially to avoid dependency on 
specialized network features. Non-write-shared operations may be continued by outstanding 
clients until all clients have been notified. The open for write does not succeed until all non- 
write-shared clients have acknowledged the callback or timed-out. 


There are no periodic cache-consistency probes. There is no explicit support in AppleShare for 


whole-file caching, due to its inefficiency on first use and on small I/O, and its requirement of a 
local disk. 
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Bluto will use a delayed-write policy, where blocks are written back to disk 30 seconds after 
being modified. This cuts write-back traffic by 20-30% [Nels88]. There will be no write- 
through on close. ‘Internal version numbers will be used to verif. consistency of data still in 
cache when a file is reopened. If the network connection is lost, the client is notified that the 
volume is no longer mounted, and its cache is flushed. The delaved-write flushing minimizes 
loss of data to blocks modified in the last 30 seconds. 


This caching scheme requires a stateful server architecture such as AppleShare. AFP k.0 will 
include support for write-sharing notification. On previous versions of AFP, only files opened 
with a Deny Write mode will be cached, since there is no explicit support for cache callbacks. 


Note that caching cannot be disabled for memory-mapped files. A mapped file is, by 
definition, always cached. The only way to ensure consistency for mapped files is to lock a page 
before reading it. For mapped files, the Bluto client will flush a page from the client's cache 
immediately (atomically) after it is locked. 


Directory and file id l 
to reduce server loa 
{Srin89]. 


The local file syst 


opened by a second process: 
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timeouts. There is no deadlock det 
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Recoverability 
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able storage, other than th 
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Support for log files will be limited to explicitly disabling caching when opening a file. 
Caching will then be disabled for the client, and optionally by the server (server cache 
disabling is server implementation dependent). Bluto also provides support for forcing any 
file's cached blocks to be written to the server's disk. This is a swnchronous flush, and can be 
used to guarantee that log files have been written to disk. 


It should be noted that disabling client caching, and flushing of server cache blocks, will 
increase server load and degrade overall system performance. 


Links 


Volumes have a fixed identifier associated with them at creation time. Bluto will allow a 
volume identifier to be seen without server access. 
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AFP k.0 will support the assignment and lookup of immutable volume and file names. 


AFP Protocol: 


Each AppleShare server encapsulates the file system objects on the remote system, and exports 
a set of operations on these objects. This set of operations is defined by the AFP network 
protocol. 


For AFP k.0, the model of network encapsulation is being changed to parallel the classes and. 
methods defined by the Pink file system. Classes remotely accessible are similar to the ones 
defined by Bluto. Instantiations of these classes may be located or created, accessed via class 
methods, and destroyed. 


For those familiar with AMP, Apple's Network Management Protocol, the approach is ver 
similar. 
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¢ The protocol will transport independent, and should run over ASP, ADSP, ASDSP, 
or TCP. 


¢ Cache callbacks for shared write files will be added. 
e Lock callbacks for shared files will be added. 
¢ File and volumes sizes will be increased to 8-byte words. 


¢ Flat volumes will be dropped in AFP k.0. 
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Desktop Database 


Bluto will implement the desktop database calls for compatibility with AFP 1.1, 2.0, and 2.1. 


Network requirements 


Bluto will continue to use ASP as its primary transport protocol. In addition, AppleShare will 
run over connection-oriented streams protocols such as ADSP or TCP. ADSP allows us to use 
larger block sizes than ASP, and has a better retransmission algorithm, but its retransmission of 
data uses more network bandwidth. Our ideal protocol is ASP with adaptive retransmission 
and larger block sizes. ASP gives us finer control over the transactions associated with one file, 
so that a file's response characteristics can be tuned by the client. This could allow us to adjust 
the protocol retransmi D Ai 
intolerant (data), or d 


High performance il mention them 
anyway. . 
Network block si: 
speed networks. 


will be 4K bytes, although we may ex Ki larger sizes on LAN 


Summ 
Bluto provides Personal Apples 
Pink, and access to remote syst 
preliminary, and feedback is welcome. 


- Much of 
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Overview of Kernel Services 


The kernel provides a basic set of services for its clients based on a few key abstractions. The 
abstractions and the general nature of the services available for each are described briefly below. 
Kernel services always have a defined scope within which they are valid. In this document we 
distinguish between local services, which execute on a single kernel and remote services, which can 
execute on different kernels separated by a bus. All kernel services are encapsulated in objects, which 
are either “real” or “surrogate”. Real objects represent entities or services that a task or team has 
directly invoked; surrogate objects represent entities or services on other tasks or teams. 


Address Spaces and Memory 
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Tasks an 


A task is an execution entity in an address space. Put another way, a task is a thread of execution. 
Tasks are the entities in the system that accomplish work; they are the units of scheduling and 
execution in the system. Traditional operating systems such as UNIX allow only one task to be 
executing in an address space at a time; in fact, the task and the address space are synonymous. It 
should be possible, however, to have more than one thread of execution in an address space at any 
given time. Having multiple tasks executing in a common address space has several advantages: 
sharing data is easy, context switch time can be reduced, and task creation time can be faster. The 
collection of multiple tasks in an address space is called a team, because the tasks will generally be 
cooperating in a concurrent fashion to implement an application or service. 


The process management interfaces of the kernel allow programs to create multiple tasks in an 
address space, to create entirely new teams of tasks in new address spaces, to get information about 
tasks and teams, and to destroy tasks or entire teams dynamically. Additional services allow tasks to 
adjust scheduling priorities to reflect the urgency they have in execution. The scope of the process 
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management services is local — tasks and teams are managed only in the local domain. 


Interprocess Communication 


In order for tasks on a team or for tasks on different teams to work together, some form of 
communication must be possible. The shared address space of tasks ona single team provides one 
means for tasks to communicate, but tasks executing concurrently or in parallel will generally need to 
synchronize their activities as well as communicate. Interprocess communication allows tasks to 
send and receive messages in a controlled and synchronized fashion. IPC models vary widely among 
different operating systems. 


The kernel provides a synchronous model of IPC with short, fixed-length messages. A task can send 
a message to another task and i is automatically blocked until the tel task has sent a ee 

message. Sucha send ETS 
understood semantics 
applications. The kerf 
and receive message 
provides a bulk data: 
spaces (and tasks). 


The interprocess 
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task, to reply to | 
processing. Ad¢ 
address space. 
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Exception Handling 


One of the goals of Pink is to allow develo 
error conditi T t 

action to tak 
application } 


provided by the 
kernel is based on tasks and IPC. By packaging a hardware exception as an IPC transaction witha 
handling task, an easily understood mechanism for dealing with hardware exceptions is achieved. 


The hardware exception handling interfaces of the kernel in particular allow a task to identify itself as 
a hardware exception handler for a team and to get and set task state information as a means of 
handling exceptional conditions. The scope of the hardware exception handling services is local — 
hardware exception handling tasks must be local to the kernel of the task incurring a hardware 
exception. 


Format of this document 


The following four sections of this document present the services available in each of the major areas 
' highlighted above. Each section follows the same general format. A section begins witha 
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presentation of the terminology associated with the area being discussed. This provides a common 
ground for the remainder of the discussion and ensures that the reader has a clear idea of what the 
terms are being used to convey. A section then continues with a detailed description of the model for 
the services of the area being presented. A section ends with diagrams of the class hierarchies 
involved in the particular area being presented. 


Much of the work in this specification is based on several other systems described in the literature. In 
particular, the Thoth system from Waterloo, the V-Kernel from Stanford, the XMS system from BNR,” 
and the Mach system from Carnegie-Mellon have had a great influence on the shape of this design. 
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Memory Management 


Terminology 


Memory management refers to a mechanism in which the stream of logical addresses generated by the 
processor is translated into physical addresses, which can be used to access real memory. The logical 
address space of a task (executing program) i is the set of addresses that it can legitimately access. The 
physical address space of the system is the set of addresses that can be used to access the RAM that 
exists in the machine; the physical address space is also sometimes used to control the I/O devices 
connected to the machine. The memory management mechanism is provided by a hardware Memory 
Management Unit (MMU). The major function of an MMU is to implement the translation operation 
described above. Along with address translation, the MMU can perform certain checks on the type of 
memory access being r f 
protection for the user. 


system. In sucha 
space, and the phy 
space is larger thar 
task's address sp 
and referenced b 


address space of the system is sometime 
> real cnaieh in the paras the operati! in nly allow pieces of a 


iddress space are required 


In a paging virttial' memory 
fixed-length units called pages: ons 
of the address space (e.g., stack, heap; ¢ 
between backing store and real memory: 
usually managed i in one of two ways. The 


page: MU's available as separate parts or integra uprocessors that 
are very cost-effective. These MMU's typically have an address translation cache that contains some 
number of the most recently used virtual-to-real translations. If a translation is needed that is not in 
the cache, page tables in memory must be searched, and the necessary entry loaded into the cache. 
This searching is either done explicitly by software after a signal from the MMU, or it is done 
automatically by the MMU itself. Strictly speaking, context switch time is very low because only a 
single MMU register (a pointer to the page table) must be loaded. However, the true overhead for 
this kind of translation process is difficult to measure. After a context switch, a task will incur a 
number of translation cache misses until its locality is effectively covered again. 


Memory Management Services 


The set of memory management services provided by the kernel must be able to support the range of 
possible MMU and system architectures that will exist in the Macintosh family of machines. In all of 
_ the memory architectures currently envisioned, the MMU provides a page-based model for the 
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address space. The MMU's differ mainly in their specific parameters and their specific operations. 
Examples of differences in parameters include page size and structure of the address space (e.g,, 
number of levels and granularity at each level); examples of differences in operations include 
translation cache flushing and address validation. For details on a specific MMU, such as the 
Motorola MC68030 or MC88200, the reader should consult the appropriate reference manual. The 
memory management services provided by the kernel are defined to operate in the local and remote 
domains — memory can be managed and controlled within a single kernel or between kernels ona 
bus. 


Kernel Memory Management Model 


The address space of a task is the set of all addresses that the task could attempt to access. On all 
currently envisioned architectures, the address space is accessed by 32-bit addresses and is four 
Gigabytes in size. The ilable for user applications varies with the particular 
MMU, but is generally 
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A segment can be created or opened for private access or shared access. A private segment is 
accessible only to the address space in which it is created or opened; a shared segment is accessible 
across multiple address spaces (TSharedSegment). Subclasses of the shared segment are provided 
(TServerSegment, TClientSegment) to support a “server/client” model of shared memory: the server 
creates the segment and allows clients to open and use the segment A segment can also be created or 
opened so that it can be accessed in a read-only or read-write fashion. An attempt to do a memory 
write in a read-only segment will generate an access fault hardware exception in the offending task; a 
read-write segment can be referenced by both memory reads and writes. In some implementations, it 
may be possible for different tasks to map the same shared segment with different characteristics in 
their address spaces as they choose (e.g., at different locations with different sizes and different access 
permissions). 


When a segment is mapped into a task's address space, a segment identifier is returned in an object 
(TSegment). This object containing the identifier can be used to refer to the segment in other kernel 

_ interfaces. Note that the segment identifier, and therefore the segment object, only has meaning 
within the team that makes the call mapping the segment. 
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A task can only legitimately access those portions of its address space where segments have been 
created or opened; attempts to reference memory where a segment is not defined are improper. 
With an MMU, an improper memory reference will cause an hardware exception, which the kernel 
will handle as needed. Such a hardware exception can either be forwarded to some other task for 
handling, or it can cause the task generating the exception to be terminated. 


The pages of a newly created segment are zero-filled when they are first accessed. Whena segment is 
subsequently opened, the specified size may be different than the size of the backing store associated 
with the segment. If the specified size is smaller than the backing store, only that portion of the - 
backing store covered by the size of the segment in the address space can be affected by memory read 
and write operations. If the specified size of the segment is greater than the backing store, additional 
pages are zero-filled and allocated to the backing store as they are referenced. 


When a task begins ex itialize its address space with several pre 


segments (e.g., a stack nent, and one or more code se Additional 
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bitmap display or th gisters of 2 a , device. As with a normal segine ical segment can be 
mapped anywhere in the virtual address space. References to these pages in the virtual address 
space are mapped directly to the physical addresses associated with the segment and affect the 
associated physical resource in a hardware-specific fashion. 


The virtual address spaces of all the tasks running in the system will generally exceed the amount of 
real memory available on the machine. The virtual memory manager will thus treat the physical 
memory as a cache for the most frequently used pages of the executing tasks. General page 
placement and replacement algorithms attempt to approximate this set of pages by observing the 
referencing patterns of the running tasks. The approximation, however, can sometimes lag behind 
the executing tasks, causing additional page faults. This lagging can often be mitigated through the 
memory management advice facility, in which a task informs the kernel of its intended use of the 
address space (TMemory). In this way, the memory manager can often have the data required by a 
task in real memory before actually being faulted for it by the task. 


In a virtual memory environment, it is sometimes necessary for certain clients to have more explicit 
control over portions of the virtual address space, especially with respect to the paging that is 
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normally transparent to applications. A service is provided that allows control operations to be 
applied to sets of pages in the address space (TMemory). These operations include locking a set of 
pages in memory, preventing them from being paged; freezing a set of pages in memory, preventing 
them from moving; flushing a set of pages to backing store, ensuring consistency of data; and 
changing the access protection (i.e., read-only or read-write) ona set of pages: 


Memory Management Classes 


alee Ny gn To ce Sich Beng Pee aS Si ee Re 
@ Registered /Restricted Opus/2 March 15, 1990 2.9.1-9 


Process Management 


Terminology 


A process is an instance of the execution of a program. A process can be thought of as an activity that 
is underway. Every process has an associated identifier, state, priority, and context (processor and 
memory management state information). Multitasking refers to a system that allows multiple 
processes to be underway at the same time. In the strictest sense, the term multitasking implies - 
nothing about the management of physical memory. A multitasking system can be built that allows 
only one process to reside in memory at a given time, with a process swap being performed on every 
context switch. Informally, multitasking is often equated with multiprogramming, which refers to a 
system that allows multiple programs to be co-resident in memory, either wholly or partially, as a 
way to increase processo ving some process ready to execute. Th . 
multiprocessing refers 


@€ mapping, 
kernel resources, etc here is little private 
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schedul- 
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line provides 
for the involuntary re removal of a task froma processor. By reallocating the processor at regular 
intervals, preemption can be used as a mechanism to provide fair sharing of the processor. This 
approach is known as fime-slicing. Preemption can also be used as a mechanism for guaranteeing 
responsiveness, by reassigning the processor whenever a task of higher priority than the current one 
becomes ready to execute. 


Process Management Services 


The process management services are based on the model of lightweight tasks on a team. The tasks 
ona team generally cooperate in the performance of some activity. This type of model seems 
particularly appropriate to the kinds of hardware architectures and client programs that are 
anticipated in the future. The process management services provided by the kernel are defined to 

‘ operate in the local domain - tasks and teams are managed and controlled within a single kernel. 
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Process Management Model 


Creation of a new team requires the creation and initialization of an address space for the team. As 
part of this initialization, several segments are created or opened in the address space. These include 
a segment for the program code being executed by the team, one or more segments for the shared 
library code and data that the program may require, a segment for the static global data of the 
program, and a segment for the stack of the root task. All other portions of the team address space 
are initially undefined. ‘ 


The set of all team root tasks is organized hierarchically according to the parent-child relationship. 
The individual tasks within a team are also organized hierarchically according to creation. The 
destruction of a task on a team causes the destruction of all subordinate tasks on the team. A team is 
destroyed when the root task of the team.is destroyed. The destruction of a root task brings, t the 
destruction of all root t escendent from that task. 
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is created. A task is aborted if additional stack space can not be allocated when required. 


Tasks can request resources from the operating system, but those resources are considered to be 
owned by the team. When a task is destroyed, resources acquired by that task, such as open 
segments, are not reclaimed, but remain the shared property of the team. Since major resources need 
not be allocated or reclaimed, the creation and destruction of individual tasks is quite fast. However, 
because the destruction of a task causes the destruction of all tasks in its sub-tree, the overall task 
destruction time is a function of the complexity of the hierarchy beneath it. Also if the task has allo- 
cated some team global resources those resources can be lost if the task dies without releasing them. 


Scheduling of tasks for processor resources is preemptive and based on the priority ordering of 


. eligible tasks. The tasks running on the available processors are always the highest priority tasks that 
are ready to execute. A priority is an integer in the range 0 to 255, with 255 being the lowest, least 
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urgent priority, and 0 being the highest, most urgent priority. Every team has a team base priority, and 
each task on the team has a relative priority with respect to the team base priority. The absolute 
priority of a task is calculated by adding the task’s relative priority to the team base priority. The 
relative priority of a task can be positive or negative. The team base priority reflects the urgency of a 
team with respect to other teams in the system; the task relative priority reflects the priority of a task 
with respect to other tasks on the same team. Figure 2.9.1-1 shows an example of task and team 
priorities. Note that it is possible for tasks on different teams to have absolute priorities that overlap. 


fel pri= 4 


Figure 2.9.1-1. Task and Team Priorities 


The assignment of task priorities should not be used by programmers as a mechanism to serialize and 
synchronize the execution of tasks. Interprocess communication or some other explicit 
synchronization service should be used instead. A task's priority represents the importance of the 
work being done by the task in relation to other work going on in the system; it can be thought of as 
a reflection of the percentage of processor cycles that should be allotted to the task. 


A subset of the highest priorities will be reserved for use by the kernel and operating system. Some 
portion of the remaining priorities may be reserved for a class of scheduling in which execution is 
time-sliced to equitably share the processor among compute-bound tasks. Still another portion of the 
remaining priorities may be reserved for scheduling tasks with “real-time” requirements. While the 
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kernel currently provides preemptive priority-based scheduling as its only scheduling policy, other 
policies (e.g., deadline or time-slot) can be implemented through servers that provide whatever 
model is desired by the various application clients of the system. 


Currently, the scheduling urgency of a given task is specified by an object (subclass of 
TTaskSchedule) representing the category to which the task should belong. These categories 
encapsulate the relative and base priorities described above. Priorities may not be set explicitly, but 
only through the use of task scheduling objects. Possible categories include animation 
(TTaskSchdeule::kAnimationTask), user interface (TTaskSchedule::kUserInterfaceTask), mouse/cursor 
tracking (TTaskSchedule::kCursorTrackingTask), CPU-bound (TTaskSchedule::kCPUBoundTask}, and 
servers (TTaskSchdeule::kServerTask). 


The tasks on a team cooperate in the performance of some activity. Since the team address space is 
shared among several tasks, synchronization of accesses to data structures becomes essential. 

Management of a shared.team-heap.is.an.example.of a facility that cannot be implemented. 
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Process Management Classes 
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Interprocess Communication 


Terminology 


The kernel provides a task model based on concurrently executing lightweight tasks. In order for 
these tasks to work together, a mechanism must be provided to allow communication and 
synchronization between them. Communication means passing information from one task to another, 
either in the form of short control messages or of large chunks of data or address space. . 
Synchronization allows two or more tasks to access shared resources (such as shared memory, CPU 
cycles, I/O, etc.) safely and in a controlled, predictable manner. This function of communication and 
synchronization between execution entities is commonly called Interprocess Communication, 
abbreviated IPC. We will adhere to this nomenclature to be consistent with the rest of the literature, 
even though it is tempting:when-talking-about-the:kernel to call it ITC (Intertask Communication). 
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basically a set of g what a task's name is composed of, what. valid, and how 
to relate a name toa specific task and vice versa. The set of all possible valid names under a given 

naming scheme is called a name space. An IPC model may require more than one name space — for 
example, it may need a name space to identify tasks locally and another to identify tasks uniquely 
across a group of machines networked together. 


When talking about providing a task identifier to name a task, issues of uniqueness must be addressed. 
If task identifiers are integers assigned in ascending order and represented by a fixed number of bits, 
then at some point in time a maximum value will be reached, and the task identifiers will start being 
assigned from the beginning values again. This could cause identity problems, so the kernel must be 
careful to insure that a task identifier is not reused too quickly after its last use. For any given name 
space, the period of time between reuse of an identifier is called its T-stability (from David Cheriton's 
V-kernel work). Obviously, it is desirable to have as large a T-stable period as possible — preferably 
on the order of years, not hours. 
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IPC between two tasks can sometimes be categorized as a client-server relationship. The client task 
requests some action or service from a server task. The server task satisfies the request, sometimes 
responding with information or a status message. This exchange is called a transaction. If the 
response gets lost somehow (e.g., if the client and server are separated by an unreliable network), it 
may be possible for the client to just reissue the request, provided no ill effects will arise if the server 
performs the same request more than once. Such a reissuable request is termed idempotent. 


Interprocess Communication Services 


The purpose of kernel IPC is to provide synchronization and control between lightweight tasks 
within a single address space or across multiple address spaces. It is a programming tool (in the 
same sense that a subrouti i ing tool) used to resolve the issues of con 
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In addition to the message-passing primitives, the kernel provides the means for local or remote tasks 
to move data between their virtual address spaces via sections (TSection and TSurrogateSection). Two 
types of sections are defined: permanent, which are created and destroyed by explicit calls, and 
temporary, which are specified implicitly in the message header and are automatically closed at the 
end of the transaction. Access to another task's (temporary or permanent) section is allowed only in 
the context of a transaction, also called a rendezvous. Message objects may be reused in subsequent 
transactions, but rendezvous-specific information for past transactions is lost. 


All task objects contain task identifiers. Surrogate task objects are used to refer to other tasks via their 
task identifier. 
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Rendezvous 


When a message is sent, a rendezvous is initiated between the sender and the receiver. The 
rendezvous is finished when the receiver replies to the message. Each rendezvous is given an 
identifier that is unique within the task identifier name domain and only meaningful in the interval 
between the send and reply and kept by the message. For synchronous rendezvous, the rendezvous 
identifier is the same as the sender's task identifier. For asynchronous rendezvous, it is a unique 
identifier for each send. A rendezvous defines a message, a temporary section (if any), legal access to 
permanent sections, a source task, and a target task. While two tasks are in rendezvous, the receiver 
can access the portions of the sender’ s address space that have been opened as permanentor ~~ 
temporary sections. 


Sender Side 
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asynchronous ) 
one-way asynch Qn i i 6 ceive/] . All three 
sets of IPC interactions have been designed so that a server task can do a Receive followed bya 
Reply and not have to worry whether the client task used Send, AsyncSend, or OneWaySend. This 
should simplify the design of servers that want to be able to handle both synchronous and 
asynchronous requests. There is also an AsyncReceive call that implements a non-blocking receive 
facility, and a ReceiveSpecific call that allows the receiver to select which message to receive based 
on sender or rendezvous identifier. Both these receive calls can be used anywhere Receive can. 


Synchronous (Blocking) 


A synchronous rendezvous is initiated using Send. Send suspends the task until the message is 
received and replied to. A sending task in this state is said to be send-blocked. A task receiving a 
message using Receive or ReceiveSpecific is suspended until a message is available. A task in this 
state is said to be receive-blocked. The two communicating tasks will synchronize their execution, or 
rendezvous, in order to pass a message. During the rendezvous, the message is copied from the 

' sending task's data area into the receiving task's data area without intermediate buffering. The 
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receiving task becomes ready, but the sending task remains suspended until the receiving task sends 
a corresponding reply message using Reply. A sending task in this state is said to be awaiting reply. If 
a task has more than one task send-blocked on it when it does a receive, it will rendezvous with the 
task whose message has the most urgent priority (priority is specified in the message header). When 
a task dies, all other tasks that are blocked on that task (i.e., receive-blocked, send-blocked, or 
awaiting reply) are unblocked and allowed to execute. An aborted ReceiveSpecific or Send will 
generate a toolbox exception. Figure 2.9.1-2 below illustrates a synchronous IPC rendezvous. The 
shaded portion of each task arrow indicates the time period the task is blocked. 


Task A Task B 


Receive 


2. Synchronous 


Asynchronous (Non 
There are two styles of asynchronous tra 
and a one-way send (using OneWaySen 
is allocated to hold the message, and the b 
queue in priority or 


message buffer containing the 7 
header). This reply. essage back to the originating task and term > rendezvous 
(additionally freeing up any kernel resources consumed by the rendezvous). The reply message is 
queued on the originating task's incoming message queue until the originator does a receive to pick 
up the message. If an AsyncSend is done to a non-existent task identifier (or the task dies before 
receiving the message from its incoming message queue), the kernel will reflect the message back to 
the originator, queuing it on the sender's incoming message queue. When the originator does a 
receive, the receiver task will be invalid. Figure 2.9.1-3 illustrates an asynchronous request-reply 
rendezvous. 


ee 
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Figure 2.9.1-3. Request-Reply Pair Rendezvous 
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Figure 2.9.1-4. One-Way Send Rendezvou: 


There are two major differences between AsyncSend and OneWaySend. The first is that a 
OneWaySend is not guaranteed to be reliable: the sender receives no indication that the message was 
or was not delivered successfully. In the case of AsyncSend, the sender will receive a toolbox 
exception if delivery is not possible. The second difference is that while sections may be sent with 
both OneWaySends and AsyncSends, in the case of OneWaySends special handling occurs. Fora 
OneWaySend the sender relinquishes ownership of the section, and deallocation of the memory is 
handled by the message object (after the receiver does a reply or immediately if the receiver no longer 
exists). Sections passed in a OneWaySend may not be referenced by the sending task after the 
OneWaySend is initiated. A light-weight task (TOneWaySendTask) is used to clean up the section 
associated with the OneWaySend and offers the convenience of sending a section and not having to 
worry about its deallocation. 
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Message Forwarding 


A receiving task can use Forward to forward a message to another task, possibly altering the text of 
the message first. The effect of a forward is the same as if the sending task had originally sent to the 
forwarded-to task. A task can determine if the message just received was forwarded by issuing the 

Forwarder call. In the case of a message being forwarded more than once, the Forwarder is the last 
task to forward this call. 


For example, in Figure 2.9.1-5 Task A sends message m to Task B, who forwards the message to Task 
C. Task C's receive call returns Task A as the sender, and a Forwarded call would return Task B as 
the forwarding task. When Task C does a reply, the reply message is sent to Task A, whose send 
returns Task C as the replier. 


Reply(m) 
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access permissions can be granted to the receiving task. Data transfer is accomplished by the 
receiving task doing a method call to get a surrogate section object (TSurrogateSection) from the 
message, and then performing Reads and Writes to the surrogate or using the stream interface. 
Access to the section is terminated when the rendezvous ends. It should be noted that sections 
provide a mechanism for copying data between address spaces. To share data without copying, 
memory management segments should be used. 


There are two kinds of sections: permanent and temporary. Both kinds can be accessed using Read 
and Write. Permanent sections are created by specifying “kPermanent” for the permanence parameter 
to the constructor, and can be accessed by any task that is in rendezvous with the task that the section 
belongs to, subject to the read/write permissions assigned to the section when it is created. 

Temporary sections are created by specifying “kTemporary” for the permanence parameter in the 
constructor and doing a Send, AsyncSend, or OneWaySend to another task. (Remember, in the case 
of a OneWaySend, the section is no longer available to the sending task!) The section is automatically 
closed when the rendezvous terminates and is accessible only by the task the caller is in rendezvous 
with. For all three types of sends, a rendezvous is defined to exist until the message is replied to. 
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A task may have multiple sections active (one temporary section and several permanent sections) at 
any given time. Permanent sections may not overlap each other. A temporary section may overlap a 
permanent section, in which case its access rights will take precedence. To facilitate connecting to 
systems with different hardware architectures (different byte orderings, size of addresses, byte versus 
word addressing, etc.), the standard stream operation Seek is used to position the stream at an offset 
to the beginning of the data, before subsequent reads and writes. 


A temporary section is associated with a message (TKernelMessage), exists only during the lifetime of 
the message (send/receive/reply), and is identified by the message's rendezvous identifier (stored 
inside the message object). Each outstanding AsyncSend can have a temporary section defined. The 
receiving task may access the temporary section and any of the permanent sections defined by the 
originator of the message data through Read and Write (or stream operations) on section surrogates 
(TSurrogateSection). Note that to get the surrogate for a permanent section to the receiver, the sender 
typically streams the secti e sent to the receiver. 


Message Priori 
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Messages in its message queue. The sender wf 

\essage header before sending the messag 
les priority has a value of 127. 
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considered the b 


£ srnel and the 

“afoemation about whether a task iden al or remote, and 
the values of the various components, will be available through library calls implemented above the 
kernel. In addition, the kernel guarantees that task identifiers will not be reused for a time interval on 
the order of years (i.e., the T-stability of kernel task identifiers exceeds one year). 


Tasks make their task identifiers known to other tasks by registering a name with some name service. 
This name service is not implemented in the kernel and thus is not in the scope of this section. 
However, for bootstrapping purposes, the task identifier of the local name server will be made 
known to all tasks in the system in some manner. 
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Interprocess Communication Classes 
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Exception Handling 


Terminology 


A software exception is an error or status condition detected by program code, such as out of memory, 
file not found, and other application-specific conditions. A hardware exception is a hardware-related 
condition caused by the execution of a task, such as a floating point exception caused by dividing by 
zero, an addressing error caused by a pointer referencing an address outside the bounds of the team's 
address space, an illegal instruction, and so on. The default action in such cases is for the task to be 
terminated with an error indication. However, these errors often are recoverable. A means must be 
provided for the excepti t.by.a.d ae handler that can fix whatever ; 
and resume execution < 
debugging. 


ation handling classes 


Exceptions can | 5. a ‘éd.to another 
task, such as a ¢ y : and the 


clients need to capture various hardwaré 
ry references, in a fashion transparent to t 


: “SOF errors, via the C++ exception mechanism, sually processes 
them. There can be deviauens to this rule in that a programmer may choose, during development, to 
have all or some specific software exceptions sent to a debugging task. A designated exception 
handler task usually processes hardware exceptions. There are categories of exception types defined 
to help the programmer: individual (ErrorType), all software, all hardware, and all exceptions. The 
name space for exceptions includes all software and hardware exceptions. The default behavior of an 
uncaught exception is task termination. 


Some exceptions can be designated as conditional, which means that if a handler is specified, the 
exception is sent to it. Otherwise, control returns in-line with no error handling. The only hardware 
exceptions that should be specified as conditional are those where returning control without 
modifying the task state cannot cause the exception to recur (e.g., Trap instructions). 
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Inline Exception Handling Model 


Pink will implement the C++ exception mechanism when Bjarne Stroustrup’s proposal is available. 
Both hardware and software exceptions can participate in the C++ mechanism and return control to 
the thread in-line. A task can specify that particular hardware exceptions are to be treated as C++ 
exceptions and can provide, optionally, a function to run to process the exception. The function can 
raise an exception or return. There is a default in-line function provided that will raise a C++ 
exception. 


Task Exception Handling Model 


A task can register itself as the exception handler for exceptions in another task or team. The 
MBaseTask and the MB =thods for ‘registering handlers, and the 
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The handler calls Receive (or WaitForMessage if two or more message classes are to be received) to 
get the exception message (TExceptionMessage). The message identifies itself as an exception 
message, indicates the exception type, and specifies the task that was running when the exception 
occurred. The message also includes other information that may aid in recovering from the exception 
(e.g., the accessed address, the value of the program counter, etc.). The handler task can repeatedly. 
do WaitForMessage and Reply calls to handle multiple exceptions. If the exception handler doesn’t 
want to process the exception, it can do a Refer call to cause the exception to be passed on to the next 
handler in the chain. 


When the handler task receives an exception message, it must either kill the offending task with a 
Destroy call, fix whatever went wrong and cause the task to resume execution by replying, or refer 
the exception on to the next exception handler in the chain. If the handler chooses to remedy the 
problem, the handler can manipulate the task's state (TTaskState) through the exception message's 
GetTaskState and SetTaskState calls and manipulate memory with Read and Write calls to the 
surrogate section (the entire address space of the task is available to the exception handler while they 
are in rendezvous). If the tasks are on the same team, the handler can also directly manipulate the 
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memory of the task that caused the exception. After the handler task remedies the problem it does a 
Reply, causing the offending task to resume execution. 


For a hardware exception it is important that the handler task either remedy the problem that caused 
the exception, kill the offending task, or refer the exception on. Otherwise, the error will recur, creat- 
ing an infinite loop. The onus is on the programmer to insure a correct resolution. If the handler task 
itself triggers an exception that it was registered to handle, both the handler and the Original errant 
task are terminated. 


Where possible, a machine independent class (THardwareException) wraps hardware exceptions. 
However, some hardware exceptions are highly machine dependent, so the task state and relevant 
exception data differs from machine to machine. For each machine configuration a definition file 
describes the machine specific classes for the machine state records, possible exception types, and 
exception message information. 
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(5) The Pink IO System. 
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Elixir IO System 


Introduction 


The Elixir IO System is a machine-independent IO model for the movement of data between 
the hardware attached to the system and the software within the system. While the Elixir 
IO System has the most machine-dependent code of the Pink system, it is based on an 
architecture the allows it to be ported to different hardware architectures as well as different. 
configurations. 


Architecture 
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end of the spectrum would contain the entire Pink system in the ROM. 


The primary goal of the Elixir IO System spawns a set of secondary goals. These are: reduced 
complexity and time to create a new device driver; automatic configuration of most, if not all 
devices; the reuse of most IO code whenever possible. Most IO policy issues regarding nearly all 
tradeoffs are architectural pushed down to the lowest level possible. Network services are 
integrated from the start as opposed to grafted on later. 


The function of the IO driver has changed significantly with the advent of the Elixir IO 

System. The classical IO driver does very little functionally, but often must fight the system if 

it wants to do anything non-standard. IO policy issues are dictated to the classic IO driver by 

the rest of the IO system (request queuing, device allocation, access policy, etc). Most classic [O 

drivers are forced into some "standard interface" form like open, close,control, etc of the classic 
Macintosh. That was the old way. 
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The Elixir IO System tries to create "standard interfaces" only when and where they make 
sense. Standardized interfaces should only be used to give good value for their constraining 
abstraction. An example of a very useful standard interface is the one between the file system 
and the mass storage devices. By abstrating away all of the messy details, the file system may 
use very diverse devices like hard disk, CD ROMs, tapes, MO disks, floppies, etc. 


Each type of IO device is likely to have differences in how it is to be accessed. Some devices 
can't be shared (printers) while others can (networks). Printers can give the illusion of being 
shared by spooling output to disk. Cards found on expansion buses may have many devices with 
different access policy issues. Clearly device access policy can't be correctly predicted for all _ 
devices today. Therefore the Elixir IO System tries not to make IO policy. Any device access 
policy that we would impose today would most likely be incorrect some day in the future. The 
Elixir IO System solves this issue by moving as much of the policy issues down to our new 
drivers. The functional role of our new drivers has been expanded from just the simple data 
movement and control of a device to also include the definition of access policy of the device. _ 
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Configuration Access Managers 


IO devices can be attached to a system via many diverse hardware paths. Some are built in on 
the motherboard, some are attached to buses (ADB, NuBus, SCSI, BLT), while others are a 
mixture of both, a NuBus card with a SCSI chip onit. A simplifying abstraction is to view 
these different hardware configurations as a hardware hierarchy. Viewing the hardware as a 
hierarchy infers we should naturally view the software for these devices as a hierarchy. The 
hierarchical view of software fits nicely in restricting the scope of knowledge to obvious layers 
of the hierarchy. By limiting the scope of knowledge we can easily push IO policy issues to the 
lowest levels of the hierarchy. 
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Configuration Access Managers are responsible for a collection of devices. The obvious example 
of this type of access manager would be the ADB access manager and its interrupt code. Besides 
providing all of the simplifying abstractions of the bus (interrupt decode, read access, etc), the 
ADB access manager will also be charged with the configuration of the devices on the ADB bus. 
When any bus access manager is started up, it would have the responsibility to find all the 
devices on the bus. After the devices have been found and identified, the given bus access 
manager would make the policy decision to spawn the appropriate access manager or just record 
that the device was found but not linked with an access manager. 


The second type of configuration access manager would be found on expansion cards (NuBus, BLT, 
etc). This type of access manager would most likely know exactly what devices are on its card, 
the exception being the case of another bus on its expansion card. This model of configuration 
access managers can be applied recursively for the bus found on an expansion card. The use of 
software hierarchy to manage an arbitrary hardware hierarchy allows the Elixir IO System to 
configure any hardwa j 
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Pink Booting Overview 


Introduction 


Designing the boot of the Pink system is one of those good news, bad news, stories. The good 
news is we get to use object oriented frameworks to solve a really messy set of problems. The bad 
news is a question: what comes first, the boot of the system or support for object oriented 
frameworks? The use of object oriented frameworks has created many circular dependencies - 
with regard to booting. 


A comprehensive design of booting will take several months to complete. This document will 
give a simple overview of how we plan to boot the Pink system. A key part of this overview is 
a list of design goals and 
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The use of a local area network as a boot device makes a great deal of sense in many of our 
markets. It should be much easier to achieve this goal if we integrate it into the booting design 
right from the start. Therefore, booting from multiple data sources will be a design goal. 


Third party developers will need to join the booting fun, but not at the expense of the user's ease 
of use. This is a hard issue because of the tradeoffs. If we constrain our developers too much, we 
lose interesting applications. If we open it up too much, the user may get confused. Simplicity 
and expansion with third party access will be another design goal. 
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The Pink Booting Sequence 


The figure below gives a simple block diagram of how the Pink system will be booted. There 
are three major sources of execution: the ROM Start Code, the Boot Memory Image, and the 
servers found in the Pink file system. 
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The Start Code 


The Pink start code design is clearly a descendant of the Blue start code design. Our start code is 
austere compared to the Blue code. The universal ROM idea for a family of design centers is 
also embraced by the Pink code. Our simplified start code will contain: 


* Memory configuration information. 

« Diagnostics for memory, IO chips, etc. 

* System feature configuration. 

¢ Default configuration of some motherboard hardware (VIAs, etc). 
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Boot Source Selection 


The details on how to select a boot source has yet to be worked out. The selection criteria will 
be based on IO hardware configuration and some sort of state information (PRAM?). Example, 
in the current Macintosh booting froma floppy has presidents over booting from a hard disk. 
Once the selection process is complete the ROM based IO code selected will read in the boot 
memory image. 


The Boot Memory Image | 


Servers bound to the shared library 


Step 1: 


Shared Library 


The Boot Memory Image is the key to resolving the object oriented circular dependencies. The 
boot image contains: the Opus kernel, the Pink file system, the Progenitor Set of toolbox servers 
bound to a shared library, and a collection of memory resident files that the file system has 
access to. 


The Progenitor Set of toolbox servers are linked with their shared libraries to create a single 
memory image. This memory image contains enough toolbox servers such that all circular 
dependencies have been resolved. The complete set of toolbox servers required is not known at 
this time. This same image could be mapped into many address spaces. By selecting the correct 
starting PC, that address space becomes the given toolbox server. (Neat trick. You can thank 
Andy Share My Library Heninger for it)! 
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Another new feature of the boot image involves the file system. This trick allows third parties 
to add to the boot image, but not be statically linked to our shared library. The Elixir IO 
System also plans on using this feature. The details on how this works is still not defined, but 
roughly it goes as follows. A magic attribute (folder?) is defined to be the boot image attribute. 
When a new file is added to this attribute set, the boot image is automatically updated to 
contain this new file. Once the file system is started up, but before the backing store servers 
have been started, these boot files are memory resident. Using standard file system access 
methods, any server in the Progenitor Set can access these files via the file system. A simple 
idea, but somewhat harder to implement. 


The last new feature is called the Conductor. The Conductor is the task who's job it is to : 
sequence through all the remaining parts of the boot process. How the Conductor knows the 
sequence is still undefined at this time. 


Now that we have defined all of the services, lets see how it works. 


and the file system. 


based boot. Still, the outline is the same: 
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KT-22 
Mass Storage I/O 


Bob Otis 
x4483 


Skiing KT-22 is like I/O - everybody wants to get through it quickly regardless 
of the obstacles placed in front of them. Sometimes they are both painful 
experiences. 
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Overview 


The purpose of this document is to set a direction for Pink's Mass Storage I/O Model. My 
definition of Mass Storage is; all devices that are used for permanent storage of data. Some 
examples would be hard disk drives, floppy drives, and Magneto Optical drives. 


Pink's Mass Storage I/O model interacts with Pluto ( for file I/O), Opus/2 (for page faults) and 
any other task that needs information from this type of device. The key components of this 
model are Device Access Managers and Bus Access Managers. The roles of each of these areas is 
defined below. | 


The following topics will be discussed in this document: 


The Mass Storagg¢ 
system, more of @ 
swapped in an 
as possible. : 


Below is a summary of the three cor 
Device Access Manager, the Bus Acces: 
shown in the diagram below, both the Dé 
OPUS/2 tasks in user space. 


The responsibitities.of the Device Access Mafiagers are th 


kernel for paging I/O. 
ce specific information. 
th the Bus Access Managers. 
e Interface with the DeskTop Objects. 


The responsibilities of the Bus Access Managers are the following: 


Interface with the Device Access Managers. 

Handle hardware specific characteristics. 

Handle device interface characteristics, such as SCSI protocol. 

Manage different sources of hardware; NuBus cards and Direct Slot Cards. 


The responsibilities of the Interrupt service routines are as follows: 


e Handle hardware interrupts 
¢« Performany I/O required. 


~ More detail can be found for each of the areas throughout this document. 
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Mass Storage has at least three clients all with different needs. The three clients I will 
describe here are the kernel (Memory manager), Pluto and the Finder. 


The kernel needs the I/O model to handle page faults as fast as possible. The interface to the 
kernel will be a frequently used for swapping memory in and out of the system. Pluto's interface 
will be used for standard file I/O and all other normal interface to mass storage devices; 
Format,Verify, Eject and others. 
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a ——— User Address Space 


Memory Manager 
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Mass Storage I/O 


File System Server 


_. 


O and 


SCSIISR 


Kernel Address Space 


KT-22 March 6, 1990 


Volume vs Physical Device 


To understand the Pink Mass Storage model the relationship between the "Volume" and the 
physical device must be explained. There is not a one to one mapping between the "Volume" 
and the physical devices. Normally, many "Volumes" will be on one physical device as shown 
below. 


In the Macintosh world today SCSI devices are divided into different partitions for different 
operating systems. To the different file systems involved this looks like multiple "Volumes", 
but to the Device Access Manager, this is one physical device. It is beyond the scope of this 
document to describe the partitioning in detail. 


One Device Multiple Volumes 


Partition Map 


Pink System 


The other relationship between "Volume" and physical devices is one "Volume" that maps to 
multiple devices. As shown below, this relationship between volume and devices is hidden 
from the Macintosh file system of today. If this relationship was available to the file system 
or a data base system the devices could be used more efficiently by evenly distributing the data 
across the different devices. One goal of the Device Access Manager framework is to make this 
information available to it's clients 


« Registered / Restricted KT-22 March 6, 1990 2.9.2.2-6 


One Volume Multiple devices 


be written without having to be concé i 
Storage Framework follows the Pink p 


calls they must understand how to interface with the manager (SCSI Manager) or the 
hardware itself (floppy drivers). 


The SCSI Manager has taken the first step by hiding the hardware implementation from the 
SCSI driver writers. This allows hardware changes to the SCSI port without modification to 
the driver. However, the SCSI driver writers still have to worry about what calls to make to 
the SCSI Manager. With the advantages of the object oriented paradigm, the file system 
interface to the Device Access Manager and the underlying hardware manager interface will be 
hidden, unless the Device Access Manager has a great need to add to the file system interface. 


The Device Access Manager writers (Pink's equivalent to driver writers) will only have to 
concern themselves with device specific software. For example: The SCSI Device Access 
Manager Framework will contain member functions that allow all of the common SCSI 
commands to be sent to the device. If a new command or modification of an existing command is 
needed, the necessary member functions will need to be added or overriden. 
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Goals 


When a project begins it is important to define the goals and objectives. This section describes 
the goals and objectives of the Mass Storage Framework. Below is a summary of the goals 
followed by a more detailed description of each one: 


To make writing mass storage device access managers easy 
To use the Object-Oriented paradigm 

To use Pink Toolbox wherever possible 

To be Fast and Efficient 

To hide device specific characteristics 

To aid (not add) to the real time characteristics of Pink 
To support all of Pluto's needs | 
To allow a ts lS O aan for Ue faults from the kernel 


interface. Differ 
of a specific I/ 
managers to in 


The mass stora 
shared between 
the future. 


Whenever possible the framework will 
wrappers and Utility Classes are two ex 
device access managers must be available 
memory. WE.CANNOT PAGE FAULT. 


ness with C++ lust be fast. 3 NOT 


mass storage I/@ 


The purpose of D Managers are to manage device specific tics, allowing 
the file system and kernel to be device independent. All non essential device information will 
be controlled by the device access manager. Some device specific information will be available 
to allow better utilization of the device. 


Pink has been defined as a real time system. The Mass Storage Framework is a key part of 
making this work. The framework will export as many functions as possible to allow real time 
access to mass storage devices. 


One client of any device driver is the file system. The Mass Storage Framework will export all 
services that Pluto requires. 


Another client is the Memory Manager to service page faults. This requires that a special I/O 
path is made available to the kernel. 
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The Finder group has indicated that they will model the real world on the desktop. In order to 
accomplish this, services will be exported from the framework that allow some measurement of 
activity to be displayed. The resolution of that activity is still to be defined. 


Since Pink is to be Apple's OS of the 90's, the Mass Storage Framework must prepare for the 
changes in mass storage devices. This will require support of larger and faster devices. Today 
80 megabytes is a standard size on Apple's mid-range computers. By 1995 it's anybody's guess 
what will be the standard. Today Magneto Optical devices are available with up to 150 
megabytes per side as well as a 1 gigabyte 5 1/4" full high disk drives. 


Architecture 


This section describes a set of Base classes that are subclasses of MTask. These classes can be 
combined with a device interface class, 


device access manage 
it's subclasses) and th 


TMassStorage is an 
device access mana 
with an interface ck 
The device access 
driver functions; . 
functions of any 


: 


A set of base cla 
for devices such as CD-RO:’ 
interface calls such as; ReadTab 
SearchForSong and others. 


The client class (TLogical Volume) is instan 
supported by a TMassStorage device. A lis 
the file system,kernel (memory manager) 
kernel this be used to access 
still to be d need devig 


op Manager 


[evel information. 
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@ Registered /Restricted KT-22 March 6, 1990 2.9.2.2-9 


Class Diagram (TMassStorage) 


TMassStorage 


TVideoVolume TAudio Volume 


Mass Storage Bus Access Managers 


Overview 


The Mass Storage Bus Access Managers are policy makers for a specific mass storage bus type. 
Mass Storage Bus Access Manager is an OPUS/2 team that is responsible for determining the 
boot policy as well as the access policy for device access managers. Each bus access managers is 
responsible for managing access to a hardware chip and the mass storage devices attached to it. 
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For example, the SCSI Bus Access Manager is responsible for the NCR5380 SCSI interface chip 
and all of the SCSI devices attached to the SCSI Bus. 


Each bus access manager consists of two functional areas; The configuration manager and the 
access manager. Below are the responsibilities of the configuration manager: 


Launching the Access Manager 

Scanning the appropriate bus for attached devices 

Identifying the device types, sizes 

bocenng and launching the associated device access manager (If available) 


The responsibilities of the access manager are as follows: 


° Manage all access to a specific hardware on the mother board 
he:hardware:impiementation from the Device Access Manager 
tocol of the bus 


Issues 


Below is a summa ‘issues that will effect the framework desig 
ottime problems. 


° nendencies on Wrappers and Runtime 1 
é d at.all times. 


see eh ee a a a ae ee 
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5 
’ rate = 10 bits/sec 


@Registered/Restricted Funnel of Love March 6, 1990 2.92342 


Architecture 


Design Philosophy 


The basic philosophy of the Nubus I/O Framework design is this: make Nubus easy for the 
programmer to understand and use. Currently, using the Blue Slot Manager, the programmer will not 
get very far without understanding an entity called the sResource (short for Slot Resource). Also 
fundamental to the Blue Slot Manager are the Slot Parameter block and the SExec Block - both ~ 
being large structures filled with fields such as séFiller1, seFiller2, spMisc, and sp Key. 


The “naive” programmer may wonder what in the world all of this has to do with Nubus, the Nubus 
cards that he is interested in, and the Nubus card's Rom and Ram. This * ‘naive” user is absolutely 
correct; the programmer need eobthe: Nabi: : AYE 
put, the easier to use, the 


For this reason, the fun 
Nubus cards, and the § 
format in order to p 
parameter blocks nor 


fe Slot Resource 
er understand large 
‘Resource structures. 


Class Over 


The Nubus Fram ay 
Framework provides a base class th 
information concerning the Nubus card 
also provides a base class that represents 
provides methods for accessing the actual sit 
a given card ina Nubus slot. 


For the sake 
more general 
base class, a Vil 
Nubus but are sk 
(TMACseDirectSlot: 


mples of this would be a ( 


Client Overview 


An example of a client that uses the Nubus and Nubus card classes to access card information 
is the (Nubus Access manager). This access manager, a team, walks the Nubus slots to 
determine which cards are resident in the system. 


A client that is only interested in the slot Resources that are on Nubus, and not the 
particular physical layout of Nubus cards, may want to simply use the Nubus base class to 
provide access to the collection of total slot Resources that are on all of the cards. 
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The Physical Nubus World 


In a sense, the Nubus I/O Framework is meant to model the physical world of Nubus. In some cases, 
the real world is so terribly abhorrent that we must attempt to shield the user from the details of 
Nubus’s wretched persona. In other cases, the “real” or physical world of Nubus is a perfect model 
for the software interfaces. One of the design goals of the Nubus I/O Framework is to model the 
physical in the cases where such as model will be intuitively easy to use, and to provide higher 
levels of abstraction where the physical world lacks clarity. : 


For example, our machines have Nubus slots, and Nubus cards go in those slots. Our computers may 
have anywhere from Zero to sixteen Nubus slots (the zero case not being especially interesting). The 
class definitions for the Nubus Framework will allow users to address the Nubus as a whole as well 
y..be.installed.on..the.bus....The classes will be flexible enough to.bhandle 
cs of communication with each café are awell 
provide at least a minimum’ 


any possible configurati 


Some machines, such as. ; will be handled just 


‘the Nubus Framework 
will use the class m: 1g Card:and thereby 
identify the card’ 


Resources are u 


The applications and most of the*eti¢ 
level operations on slot Resources. Th 
summarized as follows: 


¢ Location of Nubus cards wit 
* Loading card’s device drive 


the frightening concepts of B: 
ypes (if you don’t know what these ; 
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Clients of the Nubus Framework 


The prospective clients of the Nubus Framework are mainly system software components. 
Applications will most likely use device drivers that are loaded of the Nubus cards, for the most 
part. The software components most likely to use the Nubus I/O Framework are: 


e The boot system code, 
e device drivers,and | 
¢ low level system utilities. 


The boot code, for example, will need to walk the slots on Nubus and decide which cards he needs 
access to immediately. In the case e of a typical local boot, the video cards may have their Guvels 
tilly} awn to the screen that may be have.b : 


loaded so that a happy M 
pixel size, bit depth, and: 
information that is stor 
Framework will allow | 


In the case of a remo 
access to a bootable s 
stored in the declarat 
card to access these 


A system utility 
may need to reac 


should support many types of reco 
type of reconfiguration or status reports 
driver will lead to the use of the Nubus Fr. 
Resources. 


Class 


Es Se Se eS 
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Rob Lowe 


Video Framework | 


Video star extraordinaire, Rob Lowe, is the mascot for the Pink Video Framework. 
Rob, the ultra-talented star of many a megabuck Hollywood production - as well 
as his own, highly rated, home-made videos - breaths new life into the old shop- 
worn term: Video Framework. 


March 22, 1990 
Jeff Zias 


x44131 
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Architecture 


Philosophy of the Design 


The general philosophy of the Video driver design is the following: 


The Pink Video drivers will provide an architecturally sound framework for the processing of 
specialized video calls to control the display of colors, animation, and other user modifiable video 
parameters. 


The current Blue video device drivers provide the standard Open, Close, Status, and Control call 
interfaces. All of the different active video configuration calls are packed into the Control 

interface. The Pink video he active calls into one large call. 
The standard video oe 


myVid ; i ) 1l-bit mode 


The user of the Vid 
card type. Then, th 


t of the proper video 
proper functionality. 


The Video Framework will p 
the Video Framework base class will 
application may instantiate a class tha : ss 
device, and then have the ability to cont ‘devi For 
example, the SetNewColors member functi eycli im ion 
task’s execution. 


Applications § 
instantiate a V 
the status of agi 


The Video Frameworl its subclasses provide a higher level inte ‘the video device 


drivers - Access Managers and ISRs - that actually access the hardware. 
Eventually, much of the functionality at the interface level of the Video Framework will be 


incorporated into the Albert graphical interfaces. For instance, a Pink Palette Manager may be the 
higher level interface for SetNewColors (color table modification) type calls. 
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System Requirements 
The Pink Video drivers will be required to provide the following features: 


° Ability to easily develop new objects or Access Managers for new Video hardware. 

e Architectural foundation for implementing new animation methods. 

° Object oriented framework that shields the user (the application and device 
driver programmer’s) from needing to have any intimate knowledge of the video 
card’s internal design. 

* Reasonably fast, high-performance system. 

¢ Hardware independent architecture. 


Clients of the Vid 


t likely be clients of ramework are: 


lette Manager, 
pickers, 


Major System Components 


The primary components of the Video drive 


Driver Frame 
cess Manag 


Information Flow of the Video Framework. 


Pictured below is a proposed model for the implementation of the Video framework froma system 
component point of view. Keeping in mind that each task switch and each message can be fairly 
expensive, one of the primary design goals, speed, can possibly be increased by minimizing the 
number of IPC messages sent. 
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The cursor code is a special client of the Video Framework. The cursor code, for performance reasons, 
may need to be closely coupled with the Video Framework’s internal design. As seen in the diagram 
below, the cursor code may need to run off the video interrupts and be ready to draw the cursor from 
either the system kernel level or from a client task’s address space. For more information on cursors, 
see Don Marsh’s cursor design document. 


Applications 


Framework 


Kernel address space 


Cursor and Animation 


| Ynterrupt Manager 


i 
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The Plumbing 


(or, everything you wanted to know about a communications architecture but were afraid 
to ask...) 


Andy Atkins 
(camel trainer) 
X49215 
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This section of the Big Pink binder will introduce the roles of messages and pipes in the new 
communications architecture. The purpose here is to help you understand the issues and 
solutions without getting into the grunge of the implementation. The 411 class descriptions will 
play that role. 


This document assumes that you are already familiar with identities and clients/servers as 


described in Murf's Pathfinder document on naming and locator services and Deb Ortons's 
Scream document on the clients and servers classes. 


Introduction 


When it came time to integrate networking with the rest of Pink, we had to deal with a number 
of (possibly contradictory) goals. They were: 


ch that networking is as easy to use 
anted to make networking so 
default. 


Along the 
that we could pote : 1 the F 
and the device-driver folks were grappling with the complexities of naming as well as trying 
to bridge high-level toolbox access with the low-level mechanics. 


So the question was, how can we merge all these worlds and still provide the fastest possible 
performance? We decided that the place to do this is at the message level. Only upon 
instantiation of a message does the user need to know who it is they want to talk to. From that 
point on, the user just plugs and chugs as usual, regardless of the fact that "who" they want to 
talk to is a process on their local machine or a server on a remote machine. 
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Architectural Abstract 


Given this motivation, the Pink Team decided that Pink really. needed a generalized 
communication architecture. The purpose of this architecture is to provided a consistent yet 
extensible framework for all data communications in the Pink operating system, not just those 
confined to IPC or those across the network. This goal is achieved by the use of abstract objects 
that represent the basic building blocks of data communications. 


Messages and Pipes 


These building blocks are: 


¢ Naming and Locator Services 
See the Big Pink Pathfinder d 


atation of an identity. Wh 
xerhaps how to connect, a pipe? 

‘pipe anages the communication, includi 3 
opening and closing the pipe, keeping track of the pipe's status, and storing 
ephemeral information specific to the pipe. 


Messages - A unit of data that is sent through the pipe. A user will be able to 
stream information into and out of the message, and call send, reply, and 
forward methods. A message will actually be an abstract class definition, 
where its subclasses will implement the actual methods. For instance, an IPC- 
based message will mix-in the message definition with the TMemory class. 
On the other hand, a network-based message will mix-in the message 
definition with the TNetMemory class and provide semantics for creating 
network data lists. 
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Architecture 


The idea of messages and pipes has its roots in Deb Orton's original architecture for IPC 
messages. Her IPC wrappers (TKernelMessage) were built on the notion of a transaction, where 
one end creates and sends a request, the other end receives the request, and then replies, with 
the requestor finally getting the reply. This paradigm fit in great with what the network 
needed to do with ATP transactions. 


So in defining a generic message interface, we needed to abstract the data storage and data 
transport. With that, both network and IPC transactions were able to support similar sets of 
ssend-receive semantics while hiding the details of data storage and transport. 


First step to Nirvana 


In order to abstract the’ 
its own class (TMessa 
inherit from both the. 
message, you instanéi 
TMessage). 


Isolating the data 


new architecture, the message 
particular pipe. 


Say a user (such as the client-server classé 
first have to instantiate a pipe that knows. 


pipe. Eventi: 
returns cont 
the beauty ab 
who or where Fri 
of a message, abide by 


eh ae of a pipe, and tal mplementations 


e base class' abstract method interface. 


Beyond transactions 


We found that this architecture scales nicely to include communications that are not 
transaction-based. Say, for instance, a user wants to stream to the other side without having to 
worry about the notion of a transaction. The bytes just “magically” appear at the other end. The 
messaging semantics already described are transaction-based, so we needed to define another 
set of classes for a stream-based system. 


To be able to easily include packet or datagram communications, communications with local 
hardware devices, and anything else that requires getting bytes from the toolbox to some lower- 
level entity, is certainly a big goal of this communications architecture. 


bag Ea a a at a 
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The Big Picture 


So this brings us to the architecture as it stands today. Figure 2 illustrates the current abstract 
base class hierarchy. 


The TPipe tree defines the abstract base classes for all pipes. The TPipeDataUnit tree defines 
the set of commands that can be performed ona unit of data bound for the pipe or received from 
the pipe. Notice that the two hierarchies are rather parallel. This was done on purpose to 
reflect the fact that a particular unit of data is explicitly bound to the pipe that created it. 


Here's a quick run down on each of the classes in the hierarchy: 


¢ TPipe/TPipeDataUnit - These are the grandaddy base classes. A TPipe 
knows how to add and delete its attributes as well as "opening" and "closing" 
alter the attributes of itself and keeps 


TT'actionPipe 


TPipeDataUnit 


Figure 2. Abstract Base Classes 
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unreliable!) communications. A user can have one TDatagramPipe per entity 
and multiple packets. : 


Pipes 


Given the above hierarchy, all pipe implementations share the characteristics defined in the 
abstract superclass, TPipe. Pipes always represents the communication link. Though a pipe may 
be implemented as an object containing a surrogate task (in the case of IPC), a network service 
(in the case of networking), or as a file access mechanism (in the case of the Finder), they all - 
have the following properties: 


¢ An identity object can return a new pipe. Any identity, be it a connection- 
oriented or hiring identity, will have methods that can create a pipe. 


5 are dynamic in nature (for instance, a u 
to the pipe), the aad irises thi 
£ 


such as a pipe that manage 
the networking and SCC wo: 
real concerns. 


the messages it recognizes. See the section below on "Pipe Data Units" for 
more on this. 


Pipe Data Units 


Pipe data units, an abstraction of what we've been calling "messages" up to now, allow a user to 
send and receive data through a given pipe. As mentioned above, these data units are 
explicitly bound to the pipe it uses. The abstract superclasses (TPipeDataUnit and its 
immediate subclasses) outline the base set of methods that need to be supported by all concrete 
implementations (such as TMessage). That way, classes such as MClient and MServer can use 
any and all messages regardless of its specific implementation. 
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Data units must support some form of getting and setting attributes on the fly. These attributes 
in turn temporarily modify the pipe only for the duration of that message. A pipe data unit 
must also support some form of sending and receiving, but exactly how that is done is up to the 
abstract subclasses. 


Concrete Implementations 


From the abstract hierarchy, we were able to design a bunch of concrete classes to solve the 
communication needs for IPC and the network. Again, the communication architecture is very - 
scalable, so as future communication needs arise, we hope that they fit nicely into this 
architecture's abstract framework. 


Transaction 


To date, only concre 
concrete hierarchy i: 


sent and 
replying, and re¢ 


Example 


Here's where we present a concep 
get some information from some serve 
care. 


The first thing the server needs to do is g 
the identity to:create a pipe. From there, t 


book */ 
tribute serverLi 
etPipe(); 


TMessageé req  serverPipe.GetMessage(); 
serverPipe.ReceiveRequest (request) ; 


The client also needs to create a pipe, where one of the attributes of the pipe is the name and 
address of the server it wants to talk to. Once the client opens the pipe, it can then stream out 
the request and block on the reply. 


TIdentity clientId = PB.GetId(attribute clientList); 
TPipe clientPipe = clientId.MakePipe(); 
clientPipe.Open(); 

TMessage& request = clientPipe.GetMsg(); 

TMessage& reply = clientPipe.GetMsg(); 

data >>= request; 

request .Send(reply) ; 


The server gets the request, then replies. All the while, the client is blocked until the reply 
_ arrives. (There are other ways to do this. The client could have posted an asynchronous request 
and fetched the reply later, for instance.) 
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TNetMessage 


Finally, the client can stream out the reply. 


returned data <<= reply; 


Connection-Oriented Streams 


While the stream implementation is still on the drawing board, it is definitely a service 
needed by the network. Protocols such as ADSP and TCP suggest the use of a stream service 
interface. Not only that, but I think that we'll discover needs for local stream services, where 
the exchange of information between processes is not transaction-based. 
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Imagine, if you will, a mechanism by which one process can simply streams into an object, and 
automatically, the bytes appear in an object in another process’ address space (much like pipes 
work in UNIX). There is no need to call a Send method or a Receive method; the buffers are 
flushed and filled automatically. (This could be implemented by having the processes stream 
into a shared memory object that's mapped into both address spaces.) 


At any rate, the communication architecture scales to include the concept of a connection- 
oriented stream. The TChannel and TStreamPipe objects act as front ends to services that are 
either network-based or local. Subclassed from TPipeDataUnit, TChannel is the object into 
which you stream, while TStreamPipe, subclassed from TPipe, provides the stream transport. 


TChannel, however, is somewhat different from its sister TMessage. A streaming pipe really 
has no concept of a message or a transaction, so really, there is no way you can have many 

outstanding messages. Instead, there needs to be a single point of entry through which you can 
stream. Not only that, but streams often support several "channels" multiplexed across the 
same connection, where: 3 nique kind of data. For instance, . 
based stream may hav 
TChannels, the user 
protocol. 


TNetChannel 


TNetStream 


TLocalStream 


Figure 4: Connection-Oriented Streams Hierarchy 
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Figure 4 illustrates this class hierarchy. 


Datagrams 


The construction of an unreliable datagram interface can also benefit from the communications 
architecture. The network definitely needs a datagram service interface, and (who knows?) 
there may be other devices or mechanisms that can use this interface too. 


Not surprisingly, TDatagramPipe inherits from TPipe to provide the unreliable datagram 
service. TPacket functions as the object that contains a packet of data. There can be many 
packets for any given TDatagramPipe. Since there is neither the notion of a connection or a 
transaction, packets can be sent and received through the pipe in an essential ad-hoc manner. 


of unresolved 
me of these 


elatively new, there aré 


Connection Servers 5 
nothing more than accept co 
with the requestor, and then spi 
especially useful for connection 
connections. This could become 


¥' * 
client/servers? 


Pipe Creation - With all the discussion going on with “desktop objects" and 
"phone books", it is still unclear how these pipes will get created, and who's 
responsible for creating the identities from which the pipes are derived. 


Death Notification- It is still unclear how we are going to add death 
notification of the pipe architecture. 
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Server/Client Model 


The server client classes are intended for use in cases where two separate entities need to communi- 
cate (and possibly exchange data or objects) using request-based transactions. These entities may or 
may not be on the same team, may or may not use IPC (Inter Process Communication) and may even 
be on separate CPU’s connected through some network. There will usually.be only one instance of 
any server and multiple instances of the associated client. Client and server objects may be inter- 
mixed with other objects and even with different subclasses of themselves (i.e. a single object may be 
a client of more than one server, and a server may be a client of some other server). The exception to 
this is that any given object may only inherit or contain ONE server. No mechanism is currently pro- 
vided for handling multiple servers in a single object. 5 
Clients are not multi-threaded and by default are not multi-thread safe. Servers are also not multi- 
threaded and process requests one by one. Asynchronous handling of requests may be accomplished 
by spinning up a light-weight task to process a given request in parallel. 


achine, 
smay choose 
ad for transac- 
jatic interfaces are 


Servers and clients co 
IPC is used. For objeé 
between same-mach 
tions is slightly high 
the same whether 


In the case of both objects on the sar 
‘ork transactions are used. Deve 


ts/clients although the 
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Servers 


The server object is a light-weight task that blocks waiting for a request to arrive, processes the 
request, and then goes back to waiting for another request. Requests may be handled asynchro- 
nously by spawning a task to handle the request. Mechanisms are provided for handling excep- 
tional circumstances (client died, out of a resource etc.). Very basic servers consist of a method 
for each request the server may handle and registration of those methods in the constructor. 
Complex servers may also do special exception handling, spawn light-weight tasks to do asyn- 
chronous processing and even communicate with another server. 


Servers on the same team as their client(s) communicate via IPC (TServerMessage), but do not 
copy section information via kernel calls, rather reading and writing is done by directly touching 
the appropriate addresses. Servers on separate teams from their clients communicate via IPC, 
sections and possibly segments (TServerSegment). Servers and clients on separate machines 
communicate via network transactions. 


MServer 


MServer 


Methods for General Consumption: 

The Constructor creates a server object. This can be done either as a task or as a team. (See 
the Wrapper’s documentation for more information on tasks and teams.) 

RegisterRequest must be called from witin a sub-classes’ constructor (or some initializer). It 
registers the method name as a possible request for that server. Two flavors are provided. One 
registers the request to be handled synchronously (by the server itself); the other registers the 
request to be handled by a server helper task. 

GetDataStream returns a pointer to a data stream to be read or written. The data stream is 
NOT part of the message text and may generate a section to be sent with the message. This 
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stream may or may not be copied by setting the “buffered” flag. If buffering is FALSE, then 
every read and write will generate a kernel call to preform the operation. If “buffered” is TRUE, 
then the stream is copied into the current address space and reads and writes do not generate 
kernel calls. This stream grows automatically, as needed. 

GetMessageStream returns a pointer to a message stream which may be read or written. The 
message stream is part of the message text and is COPIED with the message when sent or re- 
turned. This stream is fixed length (approximately 120 bytes). 

Stream Operators write and read the task object piece of the server. 

HaltServer tells the server to exit. Call this method when you want to shut down the server. 
Meth for ing Information: 

GetCurrentRendezvousID returns the rendezvous identifier associated with a message and 
its sender/forwarder. RendezvousID’s are unique numbers system-wide. 

GetCurrentClient returns a surrogate task object representing the current client task. 


t makes a request with n equest string. 


end. By default the 
message is throv 
HandleSender 
valid. Overrid 
and the server. 
HandleExcep 
ReleasePend : er »s the re- 


élient that is no longer 
ssponse is thrown away 


quest or pass 

CreateServeressaxe instan ropriate | € ween 
the server and the client. Overri : : 

your message on the heap (using new} ca- 
tion. 


Methods Used for Implementation: 


in, proces 
SipnalN e 

SetMessage 
Initialize is u: 


ed internally to set/get the 
nitialize the server. 


MServerHelperTask 
Methods for General Consumption: 


The Constructor creates a server helper task object. This task object sits in a loop waiting for 
reqeusts to be forwarded by the server. By default, there is only one task per request type and 
subsequest reqeusts are queued for the helper task. 

GetDataStream returns a pointer to a data stream to be read or written. The data stream is 
NOT part of the message text and generates a section to be sent with the message. This stream 
may or may not be copied by setting the “buffered” flag. If buffering is FALSE then every read 
and write will generate a kernel call to preform the operation. If “buffered” is TRUE, then the 
stream is copied into the current address space and reads and writes do not generate kernel 
calls. 

GetMessageStream returns a pointer to a message stream which may be read or written. The 
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message stream is part of the message text and is COPIED with the message when sent or re- 
turned. 


HandleServerRequest should be overridden to implement the handling of the request. 


h for Implementation: 
HandleServerMessage implements the helpers main loop. It sits waiting for a request to come 
in, processes the request and then goes back to sleep waiting for another request. 
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Clients 


A client object may be mixed-in, be a private base class or simply a member of an object. Simple 
clients need only specify the request, package any data, and send it to the server. Complex cli- 
ents may communicate with more than one server, generate asynchronous requests, or communi- — 
cate through shared memory (TClientSegment). Each task should have its own client for any 
needed server, or the applications programmer will need to provide concurrency control within 
the client object. Mechanisms are provided for handling exceptional situations (the server died, 
out of needed resource, etc.). By default, clients start their respective servers in a separate ad- 
dress space if they are not currently running when the client sends its first request. 


Clients communicating to servers in the same address space provide some optimization for infor- 
mation transfer. Clients on the same machine, but in different address spaces communicate via 
IPC and sections (TSections) -- and possible shared memory (TServerSegment and TClientSeg- 


MClient 


m and/or a 


message stream may 
AsyncSendRequest fires off a request to the server and then continues. The-reponse must be 
handled at a later time by calling WaitForResponse or CheckForResponse. 
OneWaySendRequest fires off a request to the server and contines. If a section needs to be 
sent with the request then OneWaySendRequest will return a new segment for the programmer 
to use. 

GetDataStream returns a pointer to a data stream to be read or written. The data stream is 
NOT part of the message text and may generate a section to be sent with the message. The data 
stream is grown automatically, as needed. 

GetMessageStream returns a pointer to a message stream which may be read or written. The 
message stream is part of the message text and is COPIED with the message when sent or re- 
turned. The message stream. is fixed length (approximately 120 bytes.) 

CheckForResponse checks if there is any response fromt the server waiting to be processed. 
WaitForResponse blocks until a response from the server arrives. 

ShutDownServer sends a request to the server to shut itself down. 
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Meth J form 

GetServer returns a surrogate task representing the server object. 
GetServerName returns the filename of the server. 
IsServerKnown returns whether or not the server task is known. 
GetCurrentRendezvousID returns the current rendezvous ID. 


Meth for Extendin avior: 

HandleServerDied what to do if the server dies. 

FindTheServer how to locate the server (by default it uses the nameserver). If the server is 
not found, then this guy calls StartTheServer. 

StartTheServer how to start the server. OVERRIDE this guy tern want to start the server as 
a task (not as a team). You will need to create your server object and then start him up. 
SetRequestPriority sets the priority for a request. 

Set/GetDeleteServerOnFree tells to client if the server object (may be a surrogate) needs to be 


SetServer is used ts 
SetServerName sé 
CreateServerMe 
the server and the: 
your message on 
SetMessage & (¢ 
SectionUsed ré 


Ssage object. Create 


wn. If not, 


HandleNeedBigwe : 
HandleDataPackedInHeadé: 
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ServerMessages 


The server message object (TServerMessage) provides communication and transfer of data be- 
tween the Server and the Client. It provides a protocol for transactions between servers and cli- 
ents. Specific implementations of this class may allow communication across networks, via IPC ~ 
or possibly through shared memory. ; 


The server message inherits from the basic message object (TMessage) and adds some server/cli- 
ent specific protocol. Server and client objects are unaware of the transport mechanism used to 

handle their requests and responses and operate only on the protocol defined by the server mes- 
sage object. Any special “magic” to move transactions across networks, etc. is implemented in a 

subclass adhering to the server message protocol. 


This class is still in the design and prototype stage to support transparent networking and is 
subject to change. 


erMessage 


TServerMessage 
Methods for General Consumption: 


The Constructor creates a message object for the server and client to use. 

The Stream Operators write the message information to and from a stream. 

GetDataStream returns the section associated with the message. 

GetMessageStream returns the available portion of the message text (the piece not reserved for 
server/client communication information). 

GetSurrogateDataStream returns the surrogate section associated with the stream. 

Reply handles copying the data stream into the message (if possible) and writing any unbuffered 
surrogate sections back to the real section. 

Reset resets the message and all associated streams. 
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PackData is available to clients and servers to facilitate the packing of a request and its data. 


Meth for Implem ion: 

UseDefaultRequest looks at a flag in the message to see if a request is being passed. 
SetDefaultRequest sets at a flag in the message to signify that no request is being passed. 
GetUserStart returns the starting address of the message available to the user. 
GetUserLength returns the length of the message available to the user. 

GetMessageLength Returns the number of bytes available in the message text. 
GetRequestLength returns the length in bytes of the request id. 

PackRequest and UnpackRequest are used internally to pack and unpack the request id. - 
SignalNeedBiggerSection generate an exception stating that the section is too small for the 
response. . 

HandleNeedBiggerSection handle the exception that the section is too small for the response. 
HandleDataInMessage what to do if the data stream has been packed in the message. 


DataInMessage looks a: 
the message. The prog 
GetMessageStream(). | 
data in a section that w 
SetDataInMessage 
NeedSection checks: 
small. Unpack in t 
SetNeedSection S$ 
size needed. 

ClearFlags reset 
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Example 
Suppose I wish to build a random number server. The purpose of this random number server is to 
generate a pseudo random number for a client and also to allow a client to set the seed used for the 
number generation. This will be accomplished by building the following objects: 

1. TRandom 

This is an abstract superclass that defines the protocol for aie random num- 
ber generator. Both the server and client objects inherit from it and adhere to the 
interfaces defined here. 


2. TRandomServer : 
Only one instance of this guy is created (during startup of the system or some 

such). He registers himself with the global name server and then goes to sleep wait- 
ing for a request. There are three methods to handle the 3 possible requests: 

SetSeed, GetRandomNumber, and SetSeedAndGetRandomNumber. When a 
request arrives, the.appropriate.methad.is.called and may or may not send some..re 
sponse data back of SetSeed, no response data.t 
GetRandomN i 
third requests vu 
it to the client. 


The 
peseene 


generates a random 


helper task”), 


An example 9 processing a request asynchronously i is gi 
; to be helpful!) 
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Overview 


RedEye provides electronic messaging interconnection with the AppleMail system being 
developed for System 7. Since AppleMail for Blue is currently a few weeks away from Alpha, 
it is difficult to exactly define what it will look like on Pink. However, we expect the 
following to be true: 


¢ The existing Blue AppleMail software will probably not be able to run 


inside the Blue Adapter, requiring a rewrite for Pink. ! 

e Pink will initially support only the message client software and depend on 
the Blue implementation of the message server (running in a separate 
machine) for store-and- forward routing. 


éroperability: 
ogram-to-program message communicatia 
the user-level EMail functions. 

ateways built for Blue w 


ot work with RedEye. 
ult and how 


‘Ork services mean when t 


we are serious 
immediately upo 


Store-and-Forward Networking 


The foundation of electronic mail is a reliable delivery service that typically has 
characteristics different from other types of reliable transport protocols. The most important 
distinction is the time-frame over which the data is delivered. To allow for the 
interconnection of different mail systems, an intermediate store-and-forward step is often 
required; the time it take to complete delivery to data to the destination can range from 
seconds (for machines sharing a direct network connection) to perhaps tens of days. During this 
time, the sender machine may crash or be powered-off or otherwise lose memory state. 


lWith the Blue Adapter effort restaffed, we will explore the possibility of 
' running NuFinder extensions within the Blue Adapter as an avenue for quick 
delivery of AppleMail capability for Pink. 
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The non-immediate delivery of data has a variety of benefits that can outweigh the 
inconvenience of the time delay involved. When time is not important, data can often be 
transmitted at off-peak hours for lower communication charges. Simple economics may 

prohibit full-time network connection between users, particularly between users geographically 
distant. Interconnection with other messaging systems often go through gateways that add 
delay. For personal computers users, particularly users of portable machines, there may never 
be a time when both the sender and recipient machines are powered-on and connected to the 
network; the store-and-forward of data by a third-party agent would thus be required. 


Messaging in Pink | 


The ability for a program to create, send, and receive store-and-forward messages will be 
provided by extensions (subclasses) to the client/server framework described earlier. 

Additional methods wi 
can be called by client 


; uild authenticated 
“Tappers will handle 
“these services to 


Since much of the user value es 

consider this a special case of the mé 
service will be provided through a set of 
lower-level toolbox objects. This archit 
electronic messaging, as well as support f6 
capability. 


Finder documents:: 


RedEye will provide for the development of Personal Gateways to handle access to foreign 
mail systems in a manner similar to that used in 20/20. The development of a Personal 
Gateway for RedEye will also entail the construction of directory naming class objects that will 
be called by PathFinder and the Phonebook. The PhoneBook always acts as a central 
repository of naming and addressing information in Pink independent of the lower-layer 
networking or communication protocols involved. 


Open Issues 


Since RedEye is in such an early specification state, there are many open issues to be resolved. 
This section attempts to list the non-obvious issues that need to be considered: 


1) Overall, how can mail and messaging be better integrated into the Pink to provide user 
functions not possible under Blue? 
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2) What is the interaction between RedEye and the Pink Scripting system? How much 
scripted manipulation of the user-level mail messages should be provided? 


3) What extensions might be required for mailing large video images when running ona 
Jaguar? 
4) Can Cher use messaging to maintain shared documents between two or more users that 


do not have a direct network connection? 
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The BabelFish project is responsible for providing easy-to-use, flexible, and extensible network 
objects on Pink. BabelFish’s higher layers provide a collection of network wrappers where 
applications and other services can easily and uniformly plug into the network. The lower 
layers implement multiple protocols and links within Pink’s object-oriented framework while 
providing the hooks and abstract classes for future protocol/link implementations. 


This document will provide an overview of the BabelFish architecture. For more detailed 
descriptions, please review the BabelFish ERS (coming soon to a store near you) and the 411 
documentation. This document assumes that you are already familiar with messages and pipes, 
as described in the Big Pink The Plumbing document. It also assumes that you are familiar with 
identities, as described in the Valhalla and Pathfinder documents. 


Introduction 


The BabelFish project. 
We are doing this by: 


'y is not tied to 
yent-server model. 
bstraction and 


The BabelFish p | 
interface (API) for networ 
following concepts: 


e Simplicity: 


ietwork developers to pr 
where the standard functi 
unsuitable. 


¢ Extensibility: The API will be built upon an abstract framework 
which will allow developers to include new 
types of networking services that were not 
originally anticipated. 


All of the goals mentioned above can be achieved by using the techniques of object-oriented 
programming and by providing an abstract calling interface for developers of applications that 
will be using networking services. 
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Figure 1: Network Object Organization 
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Architectural Overview 


The network architecture is functionally split into two separate pieces. As illustrated in Figure 
1, most applications communicate with the network wrappers. Existing in the application’s 
address space, the wrappers provide a single consistent interface to the network while hiding 
the peculiarities of the protocol machinery. In using pipes, identities, and messages, the 
application may not even know that it is using the network. 


The protocol and link layer machinery, however, exists within the network team where they 
can be shared across all applications. The wrappers communicate with the network team using 
network requests constructed in a shared memory address space. Applications using the network 
are protected from each other since the network manager allocates a separate distinct shared 
memory segment for each user of the network. This manager also has the responsibility for 
multiplexing outbound aes to the appropriate protocol module and inbound messages to 
the correct shared memi 


Mix And Mat 


iatch different 
Inger implement 

dividually and then 
fnately communicate. 


In designing the low devel classes, we decided that the ability to; 


With this mechz 
ontopof IP. 


ask the wrappers to: pro : 
application does not lock itself into a particular protocol. In fact, the application t may later on 
specify a different protocol while still interfacing with the same set of pipe and message 
methods. In practice, however, the protocol used in accessing a remote service will generally be 
stored in the identity object. 


The second service provided by the network wrappers is to prepare all outgoing packets for the 
network team. With its knowledge of protocols and the configuration information provided by 
an identity, the network wrappers can automatically create network requests and add in the 
appropriate attributes. 


The application does not instantiate the network wrappers directly, but instead uses the 
methods provided by a phone book or desktop object to create identities. In turn, these identities 
dictate the behavior of the network-based messages and pipes. A network pipe constructor, for 
instance, creates the appropriate subclass of the protocol wrapper object and sets up the protocol 
_ path in the network team, all based on attributes in the identity. 


eastern ae cc a a ee 
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One of the driving forces in our design was to have the low level classes stand as an autonomous 
implementation of networking under Pink. Meaning, the network team serves the network 
wrappers but is not dependent on the wrappers. That way, the Blue network adapter or 
“critical” network applications have the ability to access the network via a special object 
(called the network team service interface) in the low level classes as just another client. 
Though this option may deliver faster throughput, the user of this object must do a lot of grungy 
preparation (such as instantiating the appropriate class of protocols and links) and fill in all 
the protocol-specific attributes of a network request. Because of these drawbacks, we believe 
that most applications will access the network via the network wrappers. 


Network Requests and DataLists 


The BabelFish architecture is centered around the network request object (TNetworkRequest), 
which acts much like a suitcase for requests that travel the network. Just like a suitcase it 
nation (called attributes). Attril 
try, and so on. 
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Abstract . 


In the sections that follow, we will briefly outline the abstract hierarchy that makes up the 
network wrappers and the network team. We will also summarize the data flow that takes 
place in both the wrappers and the team. 


Interface Classes 


The interface classes encompass those classes that are accessible to objects outside the network 
team. These classes are: 


lj, fact, the TDataList class descends from TNetworkRequest. 
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e TPipe: The TPipe class defines the object through which 
an application can submit data to the wrappers 
and receive data from the wrappers. 


¢ TPipeDataUnit: The TPipeDataUnit class encapsulates the user 
data for the wrappers. 


¢ TNetworkRequest: The TNetworkRequest class implements the 
semantically-tagged parameter blocks used to 
process all network requests. It is the object with 
which the wrappers build data to send to the 
network and receive data from the network. 


e TAttribute: The TAttribute class implements an ‘attribute’. It 


andork Wrapper C 


The goal of the high level network wrappers is to provide a standard common interface to all 
networking services. This goal is accomplished by separating the interface for acquiring 
networking services from the implementation of that service. By separating the service 
interface from a specific protocol implementation, a client application will not have to special 
case each different type of protocol the application may be using or limit that application to be 
able to use only one protocol. 


The wrappers accomplish this by implementing a service interface based on the pipe and 
message architecture. Though its service interface may be pipes and messages, underneath, it 
requires several classes for configuration, inbound message caching, and protocol management. In 
fact, the configuration classes help separate the pipe service from the protocol it uses by 
dynamically binding the protocol object with the pipe at connection-creation time. 


The following is a brief description of each of the classes that are a part of the high level 
wrappers: 
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¢ TProtocol: The TProtocol class is where pipes and messages 
interface with the protocol machinery 
(affectionately called "where the rubber meets 
the road"). It is the responsibility of the 
TProtocol class to build into the network request 
the appropriate attributes and commands given 
the protocol involved. 


e¢ TWrapperTask The TWrapperTask class helps the pipe manage 
inbound message from the network that have not : 
yet been requested by the pipe's user. We need to 
internally queue inbound packets so that we don't 
tie up the network team’s precious resources. 


¢ TConfig: 


“vstem. There are two 
routing and interface 


The low-level cla 
categories of low 
services, and 2) t 
(i.e. protocols a 
directly, the use 
low-level interfi eC 
know exactly what they’ 


The routing and interface classes used* 


¢ MNetSharedMemory 


Network Manager. It contains methods to control 
the binding with each client application, as well 
as maintains a small client data base so that the 
network team can clean up if a client dies. 


¢ TDataList This class implements the object which is passed 
from layer to layer to propagate requests. 


The protocol/link layer classes contain the code that implements the protocols and link 
connections. Listed below are brief descriptions of those classes specific to the protocol/link 
layer classes: 


¢ TNetLayer This is the parent class of all network layer 
implementations. 


& Registered /Restricted BabelFish March 15, 1990 2111-8 


¢ TLinkLayer This is the parent class for link layer 
implementations. It is a subclass of TNetLayer. 


e TDatagramLayer This class defines the generic interface to a 
packet-oriented datagram layer. ° 


¢ TTransactionLayer This class defines the generic interface to a 
transaction-oriented layer. 


¢ TStreamLayer This class defines the generic interface to a 
 stream-oriented layer. It has semantics for both 
transaction and stream data transfers, as well as 
connection establishment. 


¢ TNamerLay his:elass:define the generic interface to a naming 
yer such as NBP/ZIP. 


Data Flow: 


In this section, we 
will include object 


network team. This 


ll oes oe flow of data in both the w: 
ion; sending and receiving. 


Network 


Data flow within the n 
fact is that applications only know 
the pipe that deals with the protocol 
network request transformations. 


As already cove nt 
the pipe data units. , there is an explicit binding between the’ 
dynamic representation of the identity), and the data unit (the messages recognized by the 
pipe). 


Say, for instance, we have a situation where a client on one machine wants to send a request to a 
server on another machine. The service interface is transaction-oriented, and the underlying 
protocol is ATP. 


Before the client can send the request, the server needs to set itself up. The first thing the server 
has to do is get an identity (however that will be done), and ask the identity to create a pipe. 


/* PB is a reference to the phone book */ 
TIdentity serverId = PB.GetId(attribute serverList); 
TPipe serverPipe = serverId.GetPipe(); 
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When the server asks the identity to get a pipe (via the GetPipe method), the identity is 
actually instantiating a pipe behind the scenes. It knows what type of pipe to instantiate based 
on the type of service requested in the identity. In turn, the pipe temporarily instantiates a 
configuration object (TConfig) to help it configure itself. The reason the configuration object is a 
separate class is because many different types of pipes (TNetPipe, TNetStream, etc.) all need 
to go through the same configuration sequence. 


The configuration object does a number of things, among them, choose the appropriate protocol 
object (TProtocol) to create. It also constructs a protocol path for the network team service 
interface (TNetService) that forces the network team to set up the appropriate protocols, links, 
and bind objects. See the following section for more on the network team. Finally, the 
configuration object instantiates a wrapper task (TWrapperTask) to manage data from the 
network that has not yet been requested by the user. 


Once the configuration is complete, the server must open the pipe and post a receive. 


serverPipe. Of 
TMessageé r 
serverPipe. 


In this particular c 
network team. Th 
network. : 


The client also 
address of the 


Tide 


clientPipe.Open(); 


Reading and Writing 


block on the 


GetMsg method), the wrappers allocate a shared-memory area. The reason for this is that the 
network team has the ability to read this data without copying the data into its own local 
address space or relying on a send-with-section from the wrappers. 


Once the client sends the request, the message packages its data into a network request and 
submits itself to the associated pipe. The pipe in turn hands the message to its protocol object so 
that it has a chance to insert protocol-specific attributes and commands. In this example, the 
request is synchronous, so the wrappers simply submit the network request to the network team 
service interface and block on the reply. If the user’s send request were asynchronous, however, 
the wrappers would spawn a task to do the submission. 


Eventually, the server gets the request, then replies. 
request data <<= request; 
request .Reset (); 


reply data >>= request; 
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request.Reply(); 


Notice that the server streams the response into the same message that contained the request. 
The reason for this is that the network request object associated with the request contains 
information specifically identifying the request. If the server were to stream the reply out to a 
separate message, this identifying information would be lost, and the network service wouldn’t 
know to which request this reply matched. 


Finally, the client can stream out the reply. 


returned data <<= reply; 


Network Team Operation 


The low-level network @: 
network request (TNe 
interface (TNetService 
must do is to create 
with the attributes ni 
this consists of seve’ 
kNoOwner, which 
layer to link layer; 
indicating the hark 
with tag gSlotN 


eration.is.accomplished.at the client level using two main cl. 
quests, and the network team ser 
zests. The first thing that,a:¢ 
r to do this, a TAttribut 


yal client 
e created 
am. Normally, 
Route, and owner 


tains a text array of the names of the p 
A TTagAttribute with tag gHardwareLg 


sending requests. 


DDP: DDPWrite 


illegal command - can’t send 
through NBP 


socket/protocoltype listener 


ASPRespond /ASPWriteReply 


Table 1: Listen and Send Command Equivalents 
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COMMAND DEFINITION : 


Pause ‘ The protocols stops processing any user request and incoming packets. 
ieee aN (Sone ian raed 


Bespin cnc rates sn nes oan contention 


The protocols resumes processing incoming packets. 


GetRoundTripTime Handle ‘Echo’-type functionality. If the layer does not know how to do this, it 
passes the request to the next lowest layer. This allows the highest-possible 


layer to do timing in order to better simulate real operating conditions. 


CancelRequest 


ResumePackets 


processing incoming packets. 


GetLocalStats 


GetROConfig Returns the local configuration for addressed. 


to the next layer for it to process. 


sends the request 


eats Each protocol in the path examines th 
: p-most owner of the tag, it add 


al request, and if it is 
the reply. 


ResetPacketWin 


CancelRequest 


Table 2: Commands R pnized by a 


Listening ona 


Normally, the first thing that must be done is to listen on a channel. At least two attributes are 
required for this command: channel and listener. If the format of the channel is known, you add 
the channel attribute and attempt to open the channel. If it is not, you create a channel 
attribute, which is a template for the channel the Protocol should allocate. In the latter case, 
the channel will be added to the TDataList for future use. The AppleTalk protocol equivalents 
for the Listen command are illustrated in table 1. 


It must be noted that the use of the template channel is not always legal. ALAP, for instance, 
cannot dynamically create a channel. (Oh, I suppose it could, but currently it’s not defined that 
way!). 
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Sending and Receiving 


The Send command can then be used to send a packet (or packets). For connection-oriented 
protocols, a channel to send on may not need to be specified. The TNetService object may imply 
the channel. This is true, for instance, for PAP workstation and ASP workstation. It is also not 
required for ATP (since ATP is ‘authorized’ to create its own channel), but it is optional. ASP 
server and PAP server, however, require the channel attribute that was received via the 
incoming request in order to match the response with the appropriate request. Send requests 
also require an address to send to, as well as a TMemory object containing the data to send. 
Table 1 above suggests the Send command equivalents for some of the AppleTalk protocols. 


The ASPRespond/ASPWriteReply duplicity above can easily be resolved by the channel 
information from the corresponding incoming request. Unfortunately, the ASP workstation 
duplicity is not so easily resolved. This is handled by creating two new commands: 
‘SendRequest’ and ‘SendWriteRequest’.specifically for transaction/connection protocols 


Prevent a channel from being listened « ent, but do 


not accept incoming packets 


Free the channel for others to list 


ve packets from a specifi 


ieket (channel may: 


Prevent a channel from being listened 
not accept incoming packets 


Canceis outstanding reply - 


Table 4: TTransactionLayer commands 
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Te 
Seca 
ace 


{ Looks up a set of names based on criterion in the TNetworkKequest. In the 
absence of any other information, the domain your machine is located in is 
searched. If a list of Domains is included in the dataList, the list of Domains 
will be searched. 


EnumerateDomains: Returns a set of Domain attributes which are the domains available on the 
network. For hierarchical domains, you may specify the top level domains, and 
this will enumerate domains 1 level deeper. 


Confirms a name at a specified address/channel, or upa singlename 


GetConfiguration: Returns configuration information, including information on whether domains 


exist, and whether they are hierarchical or flat. 


Cancel: nding request 


Table 5: TNamerLayer command 


Table 2 lists the commands that all proto 
is mostly handled by the TNetLayer supet 


Deliverables 


The BabelFish project plans to ship the entire AppleTalk stack with the first release of Pink. 
We will allow the AppleTalk stack to be multi-homed. The protocols included in this are: 


¢ LocalTalk, EtherTalk, and TokenTalk 
¢ DDP 

° ATP 

e ADSP and ASDSP (secure ADSP) 

« ASP 


Services included in BabelFish include wrapper integration with the message and pipe 


architecture. We also plan on shipping an additional network toolbox to better support clients 
such as AppleShare and collaboration. 
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COMMAND DEFINITION 


CreateConnection: Establishes a connection with a specified address (and an 
optionally-specified channel). 


ListenForConnection: t Listen for a connection request. 


RefuseConnection: Refuses a connection request 


saat 
AcceptConnection: Accepts a connection request 
CloseConnection: Closes the specified connection 


Listen: Listen for incoming data on a connection 


ListenForRequests: Listen for incoming requests 


Send a reply to a read request 


Erequest which will cause data to be sent to uss! 


data on the main connection on : 


Cancel a listen request 


Cancel a listen for 


authenticate, and search for identities. Think of Pathfinder as replacing the 
machinery behind the Chooser in Pink. 


e Messages and Pipes (The Plumbing) - The Plumbing defines the wrappers’ 
interface to the user of the network. Messages and pipes are absolutely 
necessary if the network is to fit into Pink seamlessly. 


¢ Collaboration on Pink - One of our stated goals from the beginning was to 
make collaboration a default behavior in Pink. To this end, we are extremely 
interested in collaboration and intend to implement some of the ideas in 
ShareBoard on Pink. This will hopefully help drive the design of services 
built around networking. 


AppleShare - AppleShare is one of our biggest clients, and just as with 
collaboration, we hope AppleShare will help drive the design of network 
service too. 


a a ee eee 
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¢ Network Blue Adapter (Scorpion) - Scorpion will certainly exercise the 
network team’s interface and provide valuable input to the continued 
maintenance of the protocol and utility classes. 


e A-Rose on Pink (Coral Dawn) - Here again, a valuable client of the network 
team. 
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A/ROSE Is 


A/ROSE is a real-time kernel running on 68000-based smart NuBus cards. A/ROSE is a small 
kernel with task scheduling. A/ROSE is a fast kernel with fixed length IPC messages for 
delivering events. A/ROSE is a helpful kernel with procedures for moving data across the 
NuBus. A/ROSE isa friendly kernel with memory management. A/ROSE is a collection of user 
tasks called managers. These managers provide high level services including naming, inter- 
card communication, and dynamic task downloading support. 


A/ROSE is an access manager on the main logic board. The access manager provides.a subset of 
services found in the A/ROSE real-time kernel. Opus tasks use the access manager services to 
work with A/ROSE tasks running on smart NuBus cards. 


A/ROSE is a set of interface.classes. between. Opus. tasks and the A/ROSE access manag: 


A/ROSE is a set of su : 


kernel running on smart NuBus cards.: 
Uibea. ail. 


nning on the 


The access 
A/ROSE. 


The access manager receives A/ROSE fixed length IPC messages from smart NuBus cards 
running A/ROSE. The access manager forwards these messages to Opus tasks. 


The access manager moves data across the NuBus on behalf of tasks on the main logic board. 


Interface Classes 


A/ROSE is a set of interface classes between Opus tasks and the A/ROSE access manager. 


A/ROSE IPC messages can be created using the interface classes; A/ ROSE IPC messages can be 
deleted. A/ROSE IPC messages can be sent using the interface classes; A/ ROSE IPC messages 
can be received. These IPC messages are for event delivery. 
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The interface classes have methods for moving data across the NuBus. Yes, yes, I know. Only 
tasks within the same team as the A/ROSE access manager can actually move data across the 
NuBus. The interface classes really get the data to the access manager and request that the 
data be moved. . 


Support Classes for Downloading Tasks. 


A/ROSE is a set of support classes for downloading tasks to smart NuBus cards. 
The support classes find out what cards are in what NuBus slots. 
The support classes determine if A/ROSE is running on the smart NuBus card in a given slot. 


The support classes download A/ROSE to a smart NuBus card. 


The support classes é to smart NuBus cards. 


Now can anyone tell me what A/R 


I bet you can! 


A/ROSE 
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NuBus Card | NuBus Card 2 
Remote Remote 
Manager Manager Manager Manager 
User Tas A/ ROSE Name User Tas A/ ROSE Name 
3 Kernel Manager . Kernel Manager 
: ntercar ntercard 
User Tas User 136 Comm Comm User Tash User Tas 
2 2 
Manaader Manager 


User Task: 


NuBus Card 3 
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life of the system. 
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About this document 


This document provides a description of the current state of the Valhalla project. It is meant for anyone 
interested in the direction and current status of Valhalla. Readers should be familiar with the Pink project 
in general. They should also be familiar with the history of the Macintosh and Macintosh Finders. 


This is a working document. It describes what is currently known about the project. [It will be updated 
every four to six weeks. 


What is in this document? 


¢ The Valhalla project missi 


e Introduction, des¢ 
project. 


¢ Thor product 
of Valhalla. 


r interface component 


¢ Odin produ shared class library 


. These are 


‘application 


edit desk nt is of interest to anyone wh > 
tions which wish 


which manipu ates objects'‘on he desktop. Under Pink, this includes 
to create or modify documents. 


@ Registered /Restricted Valhalla March 15, 1990 31-4 


The Valhalla project mission 


Valhalla will translate Pink core technologies into concrete end user and developer benefits. The result 
will be a personal computer environment which is perceived as easicr to learn, easier to use, and more 
effective to use than any other system available. ) 


The mission of the Valhalla project is to make Pink the most compelling and productive environment 
available to personal computer users in the 1990's. 
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Introduction 


Valhalla is the Pink equivalent of the Macintosh Finder. It provides the means by which people control 
and interact with their Pink systems. Like the Macintosh Finder, Valhalla supports an interface which is 
strongly rooted in real world metaphors and is visually oriented. Valhalla is actually made up of two 
main parts, Thor and Odin. 


Thor F 


Thor is a set of user interface programs which provide end users direct access to objects in the 
metaphorical world. It is the Pink analog of the Macintosh Finder. Thor allows people to control and use 
their systems and the information on them. 


Odin 


broader than, the 
‘things which can exist 
ypes of things can be 

# editing capabilities. These 
g to operate inthe Valhalla 


Odin is a set of classes y 
desktop metaphor. T 
and all of the operatio 
added to it. Odin alse 
will be used by Tho 
environment. 


The common p 
The purpose of both Thor and Odin is 
¢ System management is the management’ 


configuration of the system. It also includ 
personal preferences. Examples are instal pplications 5 tosh. 


re'system. 
to provide 


access to the prograr t users edit documents. 
Thor and Odin are partners in these functions. Odin provides the underlying machinery for them. Thor 
delivers user level control. It is an explicit goal that the functionality exported via Thor map directly to 
core functions of Odin. 


Anyone who uses a personal computer must deal with these two issues. The degree to which they are 
made transparent, or at least simple, has a tremendous impact on people’s perceptions of the machine. 
The simplicity of performing these tasks is a key criterion which must be met in order for Valhalla to be 
considered cost effective and easy to use. 


The strategic significance of Valhalla 


Today’s Macintosh Finders present the friendliest and most productive personal computing 
énvironments available today. Despite the success of our current Finders, two situations make it 
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imperative that we develop a replacement for today’s Finders. These are: 


* New system software on classic Macintosh hardware. Pink will deliver, through software, a number 
of new technologies to our users. This will alter the entire OS and toolbox interface on the Macintosh. 
Porting NewFinder to a system with radically different underlying semantics is not reasonable. We 
must present the new Pink capabilities in a coherent manner in the Pink user interface. 


° Next generation hardware platforms. Jaguar will use Pink as its system software. Its user interface 
shell must run effectively in the Pink environment. In addition Jaguar will provide hardware support 
for new features such as multimedia input and presentation. This requires a user interface framework 
which can integrate these concepts effectively. 


Valhalla represents the next generation of Finder technology at Apple. It is a significant evolutionary 
step. Like its predecessors, it is based ona set of real world metaphors. Users can have acon 
understandable world to : 


Unlike its predecessors, 
Furthermore, it is being 
technologies such as pri 
technologies such as 


and extends them bey 
ew technologies in mi 


esktop. 
“includes software 
des hardware 


's for our customers. Some 
t,.as.welt.as. more effective 
tebt.benetits, 


Valhalla will transla 
examples include m 
use of time through: 
Valhalla will help 


ompute intensi 
being easy § 


What Valhalla is not 


It is important to understand that Valhalla is 
general services. Although it can help finda s 
accounting or architectural information. Other 
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Thor Product Description 


Thor is a set of programs which create the user environment on Pink systems. Thor presents a consistent ~ 
user model based on the Desktop metaphor. It allows people to manage their systems and the 
information on them. 


Who are Thor’s customers? 


This is really the same as asking who are Pink’s customers? Anyone who uses a standard Pink system 
will use Thor. This includes end users in business and education. It also includes developers. 


This is an extremely broad subject. It is covered in more detail in other Pink user interface documents as 
well as the Thor User Inter ificati 


For all practical purpose $0n who needs 


to use a computer. 


al customer base as any 


Key characterist 


Thor is designed witk acteristics in mind. These cz f as high level, or gencral 


benefits. 


¢ Atruly person 
under the user’s cOntro#=Si 
ed by Thor. Although Thor wi 
should interact. 


is fully 
odat- 


¢ Easy to learn. Normal people will find Thi 
Thor effectively without having to learn ar 


¢ Easy to use.. 3 : ) shed by 
providing i y 2raction ¢ all. A 
key comport u 


« Effective to use. Despite being simple to use, Thor is not limited to doing simple things. It will be 
straightforward to specify sequences of operations as well as operations on groups of objects. 


Each of these is regarded as a desirable attribute for a PC. We know of no system available today which 
is perceived as having all four of these characteristics. Although the Macintosh comes close, it 1s 
currently considered weak in terms of the “effective to use” characteristic. 


What specific benefits will Thor provide? 


From a user’s point of view, this is like asking what are the benefits of Pink? Thus, we presenta list of 
key perceived benefits, whether or not they are unique to Thor. Many, in fact, are derived directly from 
simply existing in the Pink environment. Also ,some of these benefits are already found to some extent 
in the Macintosh Finder. These are still listed as key benefits of Thor either because they are critical to the 
overall user experience, or because Thor takes them significantly further than the Finder. 
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Easy to set up a Pink system. 


This is the first problem faced by the owner of any computer system. Since Thor is our standard 
interface, it should handle this task. If Pink systems come preinstalled, this task will be simplified, but 
not eliminated. Users will be able to add and configure new hardware easily within the standard 
framework. 


Comparison with current Macintosh: 


WIth our new installer, system installation on current Macintosh systems is fairly straightforward. ~The 
greatest shortcoming of the current scheme is that it requires learning a program, the Installer, which is 
distinct from the world users normally operate in. This will not be the case with Thor. 


It is easy to install additi 


ane installation 
17Sms within the 


Software installation wil 
procedures. Thor will 8 
normal desktop frame 


Comparison with 


Installing some pack 
also require users | 
things somewhat.; 
copies. While ther 
user. 


Easy to organize things. 


Organizing things is done by means of Folde f container 


metaphor base an Object is concrete 
Comparison 


Thor’s basic mechanisni nick 


Easy to find things. 


Thor provides a variety of ways to find things. These include manual searching, as well as searching by 


attribute, by association and by content. Users may select those most appropriate method for the task at 
hand. 


Comparison with current Macintosh: 


Our original Finder supported only manual searching. Other techniques are added by things like Find 
File and ON Location. NewFinder adds the ability to find by attribute and by association. Point by 
point, here are the key differences between NewFinder and Thor. 
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* Content - Thor will be the the first Apple environment to present this ability to users in an 
integrated manner. Users can, using normal Thor techniques, find documents containing specific 
words or objects anywhere on the Desktop. 

¢ Association - Thor will handle this using a concept called Cross-references. These are similar to 
NewFinder Aliases. Unlike Aliases, Cross-references can be bidirectional and of varying 
strengths. In addition, the Thor concept of association will be integrated with the document level 

hypertext linking mechanisms in Pink. 

e Attribute - Thor does this much like NewFinder. Thor is, however, somewhat more flexible than 
NewFinder. 

e Manual searching - Thor does this just like Finder and NewFinder. : 


Lets you view the world as if it were organized in different ways. 


orld based on what you are inte >You will 
s “all 1989 documents de ‘dolphins and 
which matches your sp . This lets you 

At perspectives. 


Thor will allow you to cre 
be able to specify the sor 
fish”. Thor will create 
view the world as if it 


Comparison with current Macintosh: 


Although this is not: e are not aware of an 


Thompson-Rohrlic 


rporate this ability. John 


Reduces mistakes. 


Many computer users make mistakes wh : 
giving people adequate information about t ving: on 
rather than recall. Timely feedback about th 


Comparison 


Compared to m 
further. Consid which can be 
determined about a'gi’ orexample, if you are looking ata docum ndow and 
someone else is using it, this fact is made obvious by the state of the icon. Thor will also support animated 
icons in order to provide additional information about the state of the system. 


Reduces fear and intimidation - increases fun: 


Fear of damaging the system or of losing data is a great source of stress for many users. Thor presents a 
very safe world to our users. Requested operations either succeed or abort gracefully. The world is never 
left in an inconsistent state. Furthermore, as many operations as possible are trivially undone. This 
opens the door to stress free exploration of the system. 


People do not enjoy looking up solutions to their problems in manuals. Many will often suffer a great 
deal before picking up a manual. Thor provides easy, online, help at all times. 


Comparison with current Macintosh: 
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Once again. Today’s Macintosh does a very fine job. Compared to other systems currently available, it is 
low stress and high fun to use. There is, however, room for improvement. Thor adds multi level undo. 
Transaction based operations are also new to Thor. 


Apple’s Human Interface Group has developed promising designs for several kinds of help. NewFinder 
will implement only “what is” help. Thor, as a standard Pink application, will implement at least “what 
is” and “how do |” help. 


No wasted time due to unnecessary waiting(ban the watch): : 


On many systems, users must wait for a specified operation to finish before they can do anything else. 
Thor rectifies this problem. It always returns control of the system to the user as soon as possible. 

Whenever possible, time consuming operations are carried out by the system while the user is free to 
carry out other tasks. The gnly neerned with a previously requested Vis if 
they want to do something 


Comparison with cy 


. Thor will provide this 


¥ very 
tedious. Thor allows you to"ger : 


Comparison with current Macinté 


This sort of feature is not presently available : . 
provides some help. It is generally considere ‘ f hin 
the HyperCard environment. In addition, the ‘ 
people who can : : er Pink app! rovides 
this sort of scrip 


Specify operations on arbitrary groups of objects: 


Although you will often want to perform an operation on groups of things in the same place, there are 
times when you may wish to use other criteria. For example, you may wish to copy all of your letters ona 


particular subject to a floppy disk, regardless of where they exist in the system. Thor will allow you to do 
this. 


Comparison with current Macintosh: 


This ability is not currently available on Macintosh. Although it should be possible (within limits) under 
NewFinder, we do not expect it to be available when 7.0 is released. 


A customizable environment: 
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Many people with to customize their systems in many ways. Sometimes this is simply a matter of 
personal preference. Sometimes it is necessary due to physical handicaps. Thor is designed to allow 
many details of the interface be modified, supplemented or even completely replaced. Increasing or de- 
creasing the significance of any specific media such as sound or graphical display is easily accomplished. 


Comparison with current Macintosh: 


To our knowledge, Thor accomplishes this to a unique degree. 


Natural environment for sharing: 


The ability to share computer based resources with coworkers is usually not a natural part of most 
systems. Thor will allow sharing of all desktop objects in a simple and effective manner. This includes 
printers, documents, folder : 


Comparison with cur 
ver, still an add-on to 
its what Personal 


e mechanism for control- 
ling access to your sys 


Allows work wi 


Thor’s extensibility allows you to°wé: Thor 
can support animation or even real-ti 


Comparison with current Macintosh 


To our knowledge,.this facility is unique to The 


What featu de these benefits 


This section discusses t k technology features which will help us to nd user benefits. 
For each feature, we describe what the feature is, where the feature is derived from and what key benefits 
it helps provide. 


Extensive use of metaphor 


Metaphors allow people to formulate useful mental models of the system more quickly. The Thor user 
interface is firmly rooted in a consistent set of commonly known metaphors. Objects visible to users all 
make sense in this metaphorical world. 


The metaphors made visible through Thor are actually implemented in the Odin libraries. 
Use of metaphor helps make Thor easy to understand. This helps with benefits related to ease of learning 


and ease of use. It makes the system understandable enough that set up and configuration should not be 
intimidating. 
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Iconic interface 


Thor uses icons to represent objects in the metaphorical world. Icons help make the metaphorical world 
concrete. They are responsible for providing users with a concise and accurate view of the work. Thor 
icons can incorporate animation, video, etc to to accomplish their jobs. 


The underlying mechanisms for implementing iconic user interface elements are provided by the Odin 
class libraries. In addition, Odin provides specific iconic views of the basic objects in the system. These 
are also used by Thor. : 


With even the most basic understanding of the underlying metaphors, icons can help people find and 
organize information. Asa user’s knowledge grows, the icons can convey tremendous information about 
the state of the system. By providing timely and accurate information about the state of the system, the 
icons help reduce uncertai intimidati 


Direct manipulatio 


heir world by directly manipulating the icog 
tions of icons are translated one to one in, 


Users explore and cha 
These user level manij 
themselves. 


present specific objects. 
s on the objects 


Once again, Thor mg 


in libraries to accat 
Odin already know 


4tions into user $ 
This feature also helps*peopie is. from 


abstract commands into operations: 
This reduces significantly user intimidat 


Fast/orthogonal context switch 
When a user's i 7 yssible. : cks ina 

new window, : New icon 
or bringing as 


affected. 


There is no concept of application layers, etc. A shift of focus does not imply alot of baggage. Under the 
model of direct manipulation, only the thing being manipulated and those things naturally attached to it 
should be affected. 


This feature is principally inherited directly from various parts of the Pink application framework. 


This feature helps reduce confusion and stress. It also reinforces the feeling of direct manipulation <<<is 
it really part of direct manipulation?>>> 


Multitasking 


From a user perspective, this is the ability to have more than one thing actually happening at once. 
Simple examples include background printing and copying. 
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The principle benefit Thor derives from using Pink’s multitasking abilities is that it can always return 
control of the system to the user as quickly as possible. 


Thor derives its multitasking features both directly from the Pink application environment and by using 
the Odin libraries which are intrinsically multitasking. 


Fast feedback 


When the world can change, or when it does change, Thor makes this immediately visible to the user by 
changing the state of icons. This feature is derived from Pink’s multitasking model as well as the services 
provided by the Odin libraries. This feedback is needed to reduce fear and intimidation. It also helps 
users learn by exploring. 


Online help 


a function of being 


Online help is always in 
S learning. 


this feature reduces fe 


cation. Once again, 


Scripting 


Scrips represent se 
invoking the script 
framework. The prince 
easily avoided errors by au 


Hyper-media links 
In the Thor context, these represent user speci : terest. 
The basic techno 3) inks are 
represented in: 


Content based refri 


This is the ability to find objects based on their contents. This ability is principally derived from CHER. 
Some aspects may also be implemented in the Odin libraries. This feature is principally of benefit in the 
area of finding and organizing. 


Extensible 


Thor support s the ability to add new kinds of views for existing objects. Furthermore, it even allows the 
addition of new kinds of objects. This feature is derived from use of the Odin libraries as well as the 
general shared library feature of Pink. Thor’s extensibility allows user’s to customize their machines. 


Support for alternative presentations 
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Users can run other programs which present alternative or supplemental views of the metaphorical 
world. Thor’s operation is not disrupted by this. Thor will continue to reflect accurately the state of the 
world when alternative means are used to manipulate objects. This is directly derived from using the 
Odin libraries. This feature is an aid in letting users customize theirs systems. 


Network compatible 


Thor desktop objects can be shared over the network. In addition, Thor provides browsing abilities on the 
network. This is a function of Pink’s fundamental networking abilities plus its general client/server 
model. Network compatibility helps users share information using Thor. 
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Odin Product Description 
Odin is part of Valhalla. It is a set of class libraries written in C++. The classes which make up Odin fall 
into two groups. These are: 


* Desktop classes. These classes represent the desktop objects on the system. They provide a 
complete model of the desktop and the things you can do on it. 


* Presentation classes. These classes allow users to manage the desktop world through direct 


manipulation. They provide operations for displaying and managing desktop objects . 


Who are Odin’s customers? 


ation and 
»Some degree. 
“use Odin 


- Since Odin is responsible 
plication writers will use: 
ivalent of Finder exte 


Odin is intended for us 
management of docum 
Application writers wh 
extensively. 


What benefit 


Odin provides at 
functionality mos 
straightforward f 


using the Odi 
Comparison 
NewFinder supports a notion of Finder extensions. Finder extensions are a special class of program. 
Extension authors have the ability to blend in as part of the NewFinder interface. Odin lets any 
application author do this simply instantiating appropriate Odin classes. These are architecturally 
compatible with the rest of Pink. 

Alternate user interfaces are easily supported. 

All of the semantics of desktop objects are separate from the user interface classes. You can extend these 
easily to produce entirely new, yet compatible, presentations of the desktop world. These presentations 
can be graphical views or they may even be acoustic presentations. You can use your new classes to 


supplement the standard interface or to provide alternative views of the world. 


Comparison with current Macintosh: 
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The interface and semantics of the Blue/NewFinder desktop world are very tightlv coupled. Odin makes 
a clean split between them. The standard Odin user interface components can be completely replaced. In 
addition, supplemental interface classes can be added. The basic desktop services are unaffected by this. 
NewFinder does not support this ability. 


The desktop is always consistent. 


Odin is responsible for the consistency of the desktop world. Most of the overhead of coordinating access 
to the desktop is handled by Odin. : 


Comparison with current Macintosh: 


Blue, even under NewFinder is principally a file based world. Odin pushes the user metaphor down to 
the programming world 3 


newark for adding both 
are easily added. 


This is possible uni ings a step 
services for these 


key benefits 
Object-orie 


All Odin services are provided by well defined classes. All of Pink is based on an object oriented 
architecture. Odin fits in with this architecture. The object oriented design of Odin provides a clean model 
for understanding, using and extending both the desktop and user interface classes. 


Shared libraries. 


Shared libraries allow one program to take advantage of classes introduced by another program. Shared 
libraries are a basic part of Pink. Shared libraries provide the basis for extending the desktop world. They 
are also used for allowing arbitrary applications to use both the desktop and user interface classes. 


Client/Server model. 
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This allows, among other things, one team to coordinate and service requests from a number of other 
teams. This is a standard part of the Pink toolbox architecture. The client/server model provides the basis 
for implementing the Odin Desktop services. This provides a framework for guaranteeing consistency of 
the world model. 


Concurrency control and recovery 
In a nutshell, this guarantees that desktop operations appear to happen ina sensible order and that each 


either succeeds or aborts with no visible side effects. This is achieved through user of the Pink Credence 
classes. This feature is crucial to guaranteeing consistency of the Odin desktop world. 


Change notification for clients. 


esktop model. This is accom 
ays poll to find out the sta 


Odin will notify clients of 
This mechanism elimina 


top objects. 


a el 
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About this document 


This document is intended for anyone interested in the user interface of the Pink version of the Finder 
(Valhalla). It will also be of interest to people who want to know how Pink in general will deal with 

aspects of system configuration and organization. Readers should be familiar with the Pink projectin — 
general. They should also be familiar with the user interface presented by current Macintosh Finders. 


This is a working document. It describes what is currently known about the project. It will be updated 
as needed. 


Related documents | 
There are two other documents which describe various aspects of Valhalla. These are described below. 
¢ Valhalla Project Overview 


Describes the Valh: 
the Thor user lev 
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Introduction 


Thor is the collective name for all applications within the Valhalla project which deal with aspects 
of user interface for the Pink Finder. These programs present the system and the things it contains in an 
easy to grasp manner. Using Thor, you can manage your system and the information on it. Thor also 
allows you to easily install and configure software and hardware as well as organize and find 
information on your system. Thor is the Pink equivalent of the Finder and its associated desk 
accessories and utilities on the Macintosh. 


Thor is built upon the services provided by Odin (see related documents). Thor uses these services for 
both manipulation and display of desktop objects. 


~ 


Components of Thor 


The fundamental component of Thor is the Mjolnir application. This application is responsible for the 
overall presentation and manipulation of the desktop objects to be described later. Other components of 
Thor include such things.as.the.Macintosh.tool,.the.trash can, and any other user interface application 
which will ship as pa 
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ned to allow parts to be 
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to sit and 
operations 
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Thor Desktop Metaphor 


Overview 


Thor is designed to let normal people take advantage of the power of modern computers without having 
to become computer experts. We accomplish this by relying on the common knowledge we share about 
things in the real world. The world presented to users by Thor is that of an artificial desktop world. 
This desktop world attempts to present objects and behaviors such as those you would find in an office or 
ona desktop. By using the familiar metaphor of a desktop, users of Thor can easily manipulate the 
things they find on their computer as they would items in the real world. 


The desktop world contains things which we refer to as objects. Each object has a set of attributes 
which describe the object. In addition, each object has a set of operations you can perform on it. These 
have been crafted with two goals in mind. First, each has an important role to play in making your 
system useful. Second, each bears enough resemblance to some real world counterpart that you should 
find it reasonably understandable. 


Thor will be designed 
current Macintosh the 
and disk drives. This: 
the functionality of 
appear on the deskt 
functionality as wel 


Ippy disks 
swe will separate 
‘a floppy disk will 
oth added 


real thing and c 
also obey certaii 


Desktop Object Attributes 


Each desktop object has a set of attributes.: 
Examples include: 


¢ Who is using it now 


In addition to these attributes, certain types of desktop objects have the ability to contain other 
desktop objects. Folders, for example, can contain other folders, documents, etc. Thor allows you to 
inspect and use the contents of any container. You can use containers to organize your desktop. 


Be a a ee 
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Things in the Desktop World 
Disks & Disk Drives 


Disks and disk drives are separate entities in the Valhalla desktop world. Disk drives are objects on 
the desktop which directly map to their real world counterparts connected to the computer. Disks, on 
the other hand, appear as separate objects on the desktop. Disks can be inserted into, or ejected from, 
disk drives. Disks provide storage for other types of desktop objects such as folders and documents. In 
addition to giving you space, disks help you to organize other objects on your desktop. 


An important attribute of disks is that you need some sort of device to use and access the information on 
them. In order to use a floppy disk, you need a floppy disk drive. In order to use a CD ROM disk, you 
need a CD ROM player of the appropriate type. Of course, if you don’t have a given disk drive 
connected to your computer then a disk of that type could never show up on the desktop. 


Appearance of Di: 


ppy disks, 


masa disk 
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not be modified and 


Disks represent the v 
tapes and CD ROMs, 
resembling its real w 
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appear as locked o 


for storing information. Thes 
tnedia will be represented or 
< reflects the attributes 
3) ROM’s are read only: 


Ir computer. When they 
se they will appear with 
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Use of Disks & Disk Drives 


You use disks to store things. You can open: 
desktop object except other disks. You can 
open objects or:th disk i in order to work wi 


You can copy 
either disk 
you drop t 
disk is not large enoug d the entire contents of the source, the cop: 


Specific kinds of Disk Drives 


There are two basic kinds of disk drives you will see on almost all Pink systems. These are Fixed Disk 
Drives and Removable Disk Drives. 


Removable Disk Drives 


Removable Disk Drive is the name which decribes floppy disks or any type of disk with removable 
media. The icon for a Removable Disk Drive always shows whether or not the drive contains a disk. 


Fixed Disk Drives 


Fixed Disk Drive is just a fancy name for a hard disk. However, the name tends to convey the 
functionality quite well. Fixed Disk Drives are just like Removable Disk Drives with disks 
permanently inserted. The disks cannot be ejected or otherwise removed under normal circumstances. 
Thus, a Fixed Disk Drive always contains the same disk. 
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Thor Disks & Disk Drives vs. Macintosh Finder Disks & Disk Drives 


Thor disks are somewhat different than Finder disks. Finder disks represent both media and drives all 
rolled into one. This is the source of much real confusion and a number of theoretical user interface 
problems. Thor makes a distinction between disks and disk drives because, after all, they are two 
separate things. Thor disks simply represent the storage medium itself. Disk’ drives represent the 
hardware you use to access disks. 


ye 


ie ee ee SE A ee 
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Folders 


You use folders to organize the things you store on disks. Their behavior, not surprisingly, is similar to 
real folders. They can contain documents, other folders, etc. They are a bit more flexible than real 
world folders, however, in that you can put many kinds of things into them. In addition a folder can 
store any number of things. It is limited only by the amount of space left on the disk it is stored on. 


Appearance of Folders 


Folder icons look like folders in the real world. When opened, the folder representation will be 
changed to reflect this. 


Use of Folders 


It is extremely simple to use folders to organize things. You can create a new folder on a disk or in 
another folder. To organ mply.put. whatever you want into the folder. 


Thor Folders vs. 


Thor folders serve exé facintosh Finder folders 
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Cross-References 


Cross-references in Thor are used to tie things together. By creating a cross-reference to something, you 
can always find it by using the cross-reference. Cross-references are very much like real world cross- 
reference cards. They are explicitly not the thing itself - they merely point you to the thing of interest. 


Appearance of Cross-References | 


All cross-references will have a distinct appearance. Each, however, will have enough visual 
similarities to the thing it points to that you can recognize what it points at. 


Use of Cross-References 


You can make a cross-reference to any desktop object. Once you have done this, you can put the cross- 
reference wherever you want. Whenever you run across the cross-reference, you can use it to get at the 
real object. A simple example is. project dacuments..A project document simply contains cross- “references to 
other documents. On iment available, you can automaticalt 

things in the project. . 


Cross-references als ’. By making a Cross-refi folder and putting 
it in another folder, i 
someone else a qui¢ ay ies eating to rike elated folder. 


Thor Cross-Reé ces vs. Macintosh Finder Crog 
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references will work exactt 
within documents. | 
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Documents 


Documents are analogous to real documents or forms. Things like spreadsheets, letters and drawings are 
examples of documents. Documents contain application specific information. They normally also contain . 
some information which Thor can understand and display for you (such as cross-references). In order to 
create anew document you must have appropriate stationery for the type of document you wish to 
create. It will always be possible to get a new piece of stationery by opening up the desired 

application. In order to edit a document, you must have the application which knows how to work 
with that document. 


Appearance of Documents | : 


All documents have the same basic appearance. They have an outline which looks like a page with one 
corner turned down. Within this framework, each kind of document has its own custom appearance. 


Use of Documents 


In general, to use a d 
work with the inform 
application which | 


3 ent. When you do a Thor 
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shown information about the document. TK 
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There are several kinds of docu 


User Dossiers 


Thor is aware that different people often 
to personalize the behavior of the system b 
called a User:-Possier. 


; it can adapt to that person’s: a) 
also used for controll ess:privileges and for authentication. The ‘pass 
application preferences will also be kept in a User Dossier. 


Address Books 


Address Books help you to find and access resources external to your system. They help in keeping track 
of often used remote devices such as printers or disks. They can also be used to store addresses of remote 
systems and networks. 


Projects 


Project documents allow you to tie documents together in arbitrary ways without moving or altering the 
documents themselves. Imagine that your normal way of working involves dividing the world into a set 
of folders based on document type. One folder contains letters, one drawings and another scanned 
images. Now you need to do a project involving a few images, a drawing and a letter. You can create a 
Project by simply dragging a cross-reference for each document into a new Project. Now you can open 
them all at once by opening the Project. You never need to actually move the documents themselves. 
This approach allows you to include the same document in multiple projects. It also allows you to leave 
the original documents wherever you want them. 


@ Registered /Restricted Thor User Interface March 15, 1990 3.1.1- 10 


Viewers 

Viewers let you look at the world from different perspectives. You use them to create lists of things 
based on what you consider important. You might be interested in everything on a disk which contains 
the word “dragon” and was written over a year ago. A viewer will compile a list of such things for you. 


The entries in a viewer list are actually cross-references. You can use these to get at the actual desktop 
objects to which they refer. 


The possibility of combining folders and Viewers will be explored. 
Thor Documents vs. Macintosh Finder Documents 
Thor documents serve the same function as Finder and NuFinder Documents. Unlike older Finders, 


however, Thor can display.some.of ay document since documents can cont 
desktop objects. 


Although not current 
NuFinder by using al 


Projects could be easil 


ee ST 
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otationery 


Stationery provides a convenient and natural way to create documents. You will have a piece of 
stationery for each kind of document available on your system. The kinds of documents available are 
determined by the applications on your system. 


You can make custom stationery from any document. This lets you have different standard documents of 


the same type available. For example, you might want to make stationery for your company 
letterhead. This saves you the trouble of recreating your letterhead every time you write a letter. 


Appearance of Stationery 


Stationery looks like a pad of paper. The topmost sheet will always look like the icon of the type of 
document the stationery creates. 


Use of Stationery 
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Applications 


Applications allow you to edit documents. In general, you merely need to put the application 
somewhere in your desktop world. In some cases, you may be able to customize the behavior of some 
applications by opening them up and changing specific options. 


Appearance of Applications 


Applications will have custom designed presentations just as today’s Macintosh applications have 
custom designed icons. 


~ 


Use of Applications 


You do not normally use applications directly. The presence of a given application gives your system the 
ability to edit specific kinds of documents. 


ings about it or to modify its behavior i 
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Appliances 


Appliances in Thor are analogous to appliances in the real world such as those you would find in your 
kitchen. In the real world appliances give you a certain way to process things. For example, a toaster 

“processes” toast. In Thor, they give you standard ways of performing certain Die For example, you 
use appliances to print documents or to destroy documents. 


The key distinguishing feature of appliances is that they actively process documents instead of editing 
the contents. This processing may alter the document, it may result in hardcopy output, or it may result 
in anew document being produced. The exact results depend on the specific appliance. 


Appearance of Appliances 


Appliances look like what they represent. The Trash looks like a trash can and printers look like real 
printers. 


Use of Appliances 
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Printers 
Not surprisingly, you use Printers to print documents. To print a document, you simply drop it ona 
Printer. The Printer will print the document and put it back where you took it from. 


Thor Appliances vs. Macintosh Finder Appliances 


Appliances are analogous to NuFinder Grinders. 
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Tools 


Tools are like little utensils. They have no associated document types and they do not process 
documents. They are used to perform certain small, well-defined tasks. Tools may have state which is 
saved between uses. 


Appearance of Tools 
Tools look like the kind of thing they represent. 


Use of Tools . 


To use a tool, you open it up and use it directly. Each kind of tool will present an interface which is 
appropriate for what it does. 


Specific Kinds of Tool 


Thor will provide seve 
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Thor Tools 


Tools take the place of a number of old Desk Accessories. They are meant to serve much the same 
function: to be quickly accessible and used for simple tasks. 


i 
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Components 


Components in Thor are parts of other things. Applications, for example can contain several different 
components such as a spell checker or fonts. The key aspect of components is that they have no 
functionality in and of themselves. They are only useful when they are inserted into some other kind of 
desktop object which can make use of them. Thor has no way to look inside of components. This is in 
contrast to other kinds of objects where Thor can normally show you what they contain. In general, you 
won’t need or want to deal with Components. 


Appearance of Components 


~ 


Components will look like little black boxes. They will normally appear within applications when 
they are opened. They can, however, live anywhere in the desktop world. 


Use of Components 
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About this document 


This document describes Odin, the suite of classes and methods which allow all Pink applications to deal 
with desktop objects. Through the interface described herein, any action represented by the Finder appli- 
cations (collectively called Thor) can also be accomplished from any application. In fact, Thor will be 
using these same classes to do its job. 


This document will give the developer of a Pink application enough background to use and understand 
desktop objects. We do not list nor discuss actual method calls, except as examples. Nevertheless, read- 
ers should be familiar with the Pink project and C++ in general. 


This is a working document. It describes what is currently known about the project. It will be updated as 
needed. 
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° Thor User Interface Specification, describes the Thor user interface. This includes a description of 
objects on the desktop and how they are manipulated by the user. This document is of interest to 
anyone who wants to understand the user view of Valhalla in detail. 


¢ Valhalla Construction Manual, contains the “secret wisdom” of Valhalla. This includes detailed 


architectural and implementation information. It is of interest to those who are involved in 
building or reviewing Valhalla as a whole. 
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Introduction and Overview 


According to Norse mythology, Odin is the great magician/ warrior of Valhalla, the one who orchestrates _ 
the battles of myriad brave warriors, and who conjures up the necessary magic for their success in war- 
fare. Together with his son Thor—the greatest of all warriors—Odin sees to the continued success and 
welfare of the North countries. 


In the Pink system, the Odin libraries and servers provide the necessary magic for all applications to suc- 
cessfully manipulate desktop objects. Odin orchestrates the communication between applications and 
desktop objects, coordinates multiple requests to the same objects, and allows for simple and consistent 
presentation to the user. Together with the collection of applications that make up the Finder (known as 
Thor), Odin has the stewardship and responsibility for the desktop metaphor and the desktop world. 


Benefits of Odin 
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Odin provides the benefits of consistency to bg 
tive, the direct sree Cena so prevalent in tt 
look and act the:same: 
the user's pref 
across the syst 


From the developer’ ctions that the user performs to deskti ave a direct corol- 
lary in Odin’s interface to these same objects. All file system operations are expressed in terms of desktop 
objects, and their effects are immediately reflected in that arena. No longer does the developer have to 
think in one mode (the File System) while presenting another (the Desktop World). In addition, the stan- 
dard presentation of each object is previously defined and available for use by the application. 
Reinventing the user interface is no longer necessary. 


Overview of Desktop Objects 


We use the term “desktop objects” to generally describe anything that the user can move around. The 
term makes sense historically as any object which the Finder manipulated can be placed on the desktop. 
In Pink, the definition still holds, but the emphasis has shifted from the Finder to all applications that 
show any manipulable objects to the user. 


Desktop objects in Odin reflect the attributes and contents of the real “thing”, such as the trash, a 
document ora disk. They model the behavior of the desktop object. All information about a desktop ob- 


ject obtained through the Odin interface will map to some concrete attribute of the real object. These at- 
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tributes run the spectrum from very concrete (geographic location, say, of a printer) to much less concrete 
(color of a document when presented on a monitor). Any changes to these attributes made through Odin 
will make a real change to the desktop object that is represented. 


Each desktop object can be thought of as a potential container of other desktop objects. This is familiar to 
users of the current Finder, especially in the case of folders and disks. This concept now extends to all 
desktop objects. Even documents may contain, say, a cross-reference to another document, or a special- 
ized spelling database that can be dragged to other documents. 


The corollary to “containership” is that every desktop object is contained by another desktop object? We 
get around an infinite hierarchy by having one exception: the Desktop itself. We define the Desktop to 
be a “desktop object” but with the key exception that it does not have a container (or home) itself. This, 
of course, implies that the Desktop itself cannot be contained by other desktop objects. 


Presentation of Deskt 


The programmatic interfj del the behavior of 
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Operations on Desktop Objects 


When dealing with desktop objects through Odin, there are some basic concepts and rules which must be 
understood. These “desktop axioms” provide a framework for operations on desktop objects. They deal 
with how desktop objects deal with those who make requests of desktop objects, concurrency, and the 
side effects of operations. 


The desktop axioms are listed below. 


Operations 


Any task can make a request of a desktop object. The corollary to this is that multiple tasks may 
be making concurrent requests of a single desktop object. . 


The requesting task blocks until its request completes. If a particular application wishes to make 
concurrent requests to objects, then it is secne med to spawn multiple tasks. 
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@ effects. If it failed, the regi ot carried out 


out completely a1 
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A valid key is ered as a result of a successful acquire. 
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fecting 


There are many operations which desktop objects may perform. They are described in detail in the head- 
er files for the Odin classes themselves. Below we list some of the general operations available to all 
desktop objects, i.e., the methods supported by the most abstract desktop object. 


Acquire/Release—Before any change can be made to a desktop object, it must be acquired. 
Acquire will return an “acquire key” by which side-affecting operations may be authorized. It is 
not possible for anyone else to acquire an object until the particular key is released. 
Lock/Unlock—Make a desktop object write protected or not. 

Move—Move a desktop object to a new position within its container. 

Dispose—Dispose of a desktop object completely (note: this is not the same as moving a desktop 
object to the Trash object). 

GetContents—Get the contents of this desktop object. 

GetContainer—Return the container in which I reside. This will succeed for all desktop objects, 
except the Desktop itself. 

GetName/SetName—Get or set the name of the desktop object. 
GetComments/SetComments—Get or set the comments associated with a desktop object. 
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¢ AddDependent/RemoveDependent—An application may add a dependent task to a desktop ob- 
ject. Whenever an attribute of the desktop object changes, the task is then notified of the change. 
Dependents may be added based upon particular attributes. . 

° GetAttributes/SetA ttributes—Get or set the specific attributes associated with a desktop object. 


Besides the operations available to abstract desktop objects, specific operations may be added by classes 
derived from desktop objects. As examples, a document may be moved from one container to another 
(within the same disk), a disk may be unmounted, a disk drive may eject a removable disk. 


Sample Odin Classes 


Odin defines classes which represent real desktop objects and make them accessible from all applications. 

The desktop object instance which we manipulate within an application is a representation (or “surro- 

gate”) of the real desktop object (say, the disk or document). This implies that any change to a desktop 
theimumediately-visiblein Application B. 


ects which pro- 


¢e (say, a document or, fol 3) everything else 


2 4 
esktop Object f 
3, 


”TDTFixed Dish 
TDTRemovableDisk: 


Although this is not an exact hierarchy of clas 
for our examples (the abstract classes will be c 
TOther for now) 


TDesktop theDesktop; 


The desktop can then be used to find out about other objects (disks, etc.) that may be contained in the 
desktop. In the future, it may be that the application framework will provide other default desktop ob- 
jects. For instance, an application which opens a document may be provided with the desktop object that 
represents that document. 


Once you have an instance of a desktop object, you can query it for information about itself, its container, 
and the objects it contains. For instance, we can query the desktop what objects it contains. 


TDesktopObjectSet theContents; 
theDesktop.GetContents (theContents) ; 


The set of desktop objects returned by GetContents is a snapshot of the contents at the time the call was 
made. Since other applications (or even other tasks within the same application) could be updating the 


i 
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contents as soon as the GetContents call is done, there is no guarantee that theContents is eternally accu- 
rate. 


Assuming a relatively stable world, the following would allow a recursive descent through every desktop 
object in a system. 


void descend(TDesktopObjecté& thisObject) 

{ 
// This is the point at which you would do something to the object 
// say, print its name, whatever 
DoSomethingTo (thisObject) ; 


// get ready to descend 
TDesktopObj 
thisObject; 


{f iberat. 


tterator (theCon 
ect aDesktopObject; // sti 
= theIterator.First(); / 


sktop object here 
first one 


TDesktop theDesktop; 
descend(theDesktop) ; 


Creating a Ne 


“but has some addition i 


In order to create a ne ject, it is necessary to provide enough in hat the new ob- 
ject may safely live in its new home. Therefore, it is at least necessary to specify the desktop object in 
which the new object will live. Most objects also expect a name or other specification so that it can be cre- 
ated unambiguously. 


The actual creation takes place within the application by specifying all the necessary information to a con- 
structor of the type of object you wish to create. 


// create a new folder in parentObject with the name "New Folder" 
TDTFolder newFolder (parentObject, TText ("New Folder") ); 


// create a new text document on the desktop with the name "Read Me" 
TDTDocument newDocument (theDesktop, TText (“Read Me"), DocType(kTextDoc) ); 


// connect a new hard disk to the desktop by specifying SCSI port 
TDTFixedDiskDrive newDisk(theDesktop, IOSCSIPort (kSCSI5)); 
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It is not possible to create an “abstract” desktop object directly. There is no constructor, say, for creating a 
generic Space User which would be specified more concretely later. 


Desktop Objects in the Application 

In order for a desktop object instance to be useful, they must be lightweight and easily replicated. Once 
you are given an instance of a desktop object class, you can access it, duplicate it, and transform it into 
more or less abstract classes. All these instances will still refer to the same “real” desktop object. Since 


these classes are very lightweight, there is little penalty for the duplicate versions. 


// we are given “anObject" of type TDesktopObject 
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The general rule tS any instance of desk 


on. This is evident i ! 13 jectSet and TDesktopObjectSetlterate: e the more 
general collection classe 4 rm copies of the items collected within ther like fashion, the 
TDesktopObjectSet will dispose of any storage associated with its contents when the set itself is deleted. 


Any instance of desktop object garnered from the set before its destruction is still valid, however. 
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Presenting the Desktop Object 


The presentation classes will ultimately exist as a shared library accessible to any pink application. 
Applications will make use of the presentation server as a means to decide what type of presentation 
class to instantiate. An application will give the presentation server certain user information, attributes 
and characteristics which the presentation server will use to make a decision about what type of 
presentation class to pass back. 


The application will be able to specify arbitrary attributes for use in the process of selecting a presenta- 
tion. The presentation server will then pass back some sort of identity which will specify a given 
presentation from the global presentation database. The application can then instantiate a presentation of 
this type. If the presentation server passes back more than one type of presentation identity then the 
application can pass back each of the types which it was given along with some more information to 
allow the presentation server to narrow the choices down to a single one. 


Following is an example of 
by icon. If the user then 
server for each of the obj 
attributes which the app 
server would then pass 
the object. 


pose a given window is dis layit ries of tools 
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How the Magic Happens 


Throughout this document we have emphasized that the Odin classes create instances which refer to the 
desktop object, but are not the object itself. This section goes into more detail as to how this magic is car- 
ried out. NOTE: It is not necessary to know or understand this section in order to use the Odin classes. 


There exists on each system a “desktop server” whose job it is to manage the requests made to desktop 
objects. Every request that is made by an application to an instance of an Odin object gets forwarded to 
the desktop server. : 


For each item that can appear on the desktop there is a specific central desktop object within the desktop 
server that provides the information about that item. These desktop objects provide the real link between 
the “real thing”—a disk, a file, a printer—and the information returned to applications. Central desktop 
objects are not generally c j ation about the object is presented, bu with 
the accurately reflecting t! sy represent. Central desktop objects: 
model of the state and be snted on the desktop. 


Central Desk 


While each request is made synchronously at its source, the desktop server must be able to handle multi- 
ple requests asynchronously in order to serve multiple tasks and teams. Therefore, each request that 
comes to the desktop server gets handed off to a separate task, which then makes the request of the ap- 
propriate central desktop object. When the results of the request are known, the task replies back to the 
application with the results. 


Eas Te a i a I es i BN ee 
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Mood Indigo 
The Blue Adapter 


by 
Rick Daley, Phil Goldman, and Rick Holzgrafe 
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Introduction 


The Blue Adapter is a crucial piece in the Pink system. It will allow Pink users to run most of the 
large base of Blue applications, as long as the target machine is a Macintosh with a 68xxx-family CPU 
(as in every Macintosh shipped to date). It will also support many INITs, FKEYs, DAs, and CDEVs. 
The adapter may not support Blue code that must run at interrupt time in order to function correctly. 
It therefore may not run some drivers nor applications that depend on such code. 


The adapter is not a window onto an underlying Blue system and/or ROM. Rather, it is an 
emulation of the Blue application execution environment. Therefore, features added to Blue must be 
explicitly added to the adapter as well; they will not magically appear. 


With the addition of MMU 
potentially larger add 
Blue system. 


the adapter will provide for more. nda 
e virtually indistinguishable.£ 


Architecture 
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to the approach 
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to MultiFinder when they are willing to ” 
“unblock-and-run” message as a token w 


and drivers 
support from 
new features from 


dapter emulates Blue capab low level, 


am nd later Blue releases should be easy t 
We currently assume that the important Blue applications will be 32-bit clean by the time the Blue 
Adapter ships. If not, there are options we can pursue. (It might be possible to run 24-bit applications 
along with 32-bit ones, by running all the 24-bit applications in the first 16M, never showing them 
addresses 2 16M, and handling the faults caused when they put garbage in the high byte of 
dereferenced pointers by giving them the access from the stripped address.) 


There is a limited amount of protection that can be provided in one address space. Applications can 
have their particular heaps protected, but the rest of the space (including the Blue “low memory” 
image, the system heap, and temporary memory) cannot. There would be a loss of efficiency, since 
the access levels on the heaps must be changed at every switch. The adapter itself will be more 
complex and thus more difficult to extend. A better solution might be to have 256 shared areas that 
represent the same 24-bit world. 
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Implementation Issues 


Extensions 


The following are services that the Blue Adapter may provide, but which are not critical to the 
adapter’s success: 


° Run INITs when the adapter is launched. 

° Support accessto memory-mapped hardware, either by actually mapping in the I/O 
memory space, or by trapping exceptions and simulating the access in software. 

e Support all the private MultiFinder calls, to support SADE and shady third-party stuff 
(e.g. Suitcase). 

* Create a wrapper to allow some Blue drivers (e.g. video and SCSI disk drivers) to work 
with the Opus I/ O model 


Evolution 3 


One of the great 
other part of the | 
Blue alike. There 
yet, some of the 
is not 32-bit cle 
the future, we £ 


he Blue fees mes lies. at more than any 


we may have to emulate vironment.) So, until we see 
aptions about it. The 2 ently suffice: 


developer co tem 7.0 pr s will 
be 32-bit clean well : : 


° Evolve the adapter as Pink 
Event and Layer Servers, th 


pported by the'a apter. We must not only follow these di elopments, but also 
advise the developers. The System 7.0 IPC interface is an example of such evolution, 
where advice from the Pink team is helping to shape Blue development for future Pink 
compatibility. 


External Dependencies 


The Blue Adapter is a high-level Pink application. Like any such application, it has dependencies on 
the services provided by the Pink system. 


The adapter needs the following kernel level services: 


A timely method for receiving A-line exceptions. 

Emulation of privileged instructions. 

Reception of bus errors, in some form, for exception handling. 
A method to map in ROM and screen memory. 
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. A timer service, to support the Retrace Manager and the Time Manager. 
° A way to synchronize with the hardware, most obviously the vertical retrace of the 
monitors. 


The following services provided by the Pink Toolbox (shared libraries or eee) are necessary so 
that the adapters can share common resources at this level. 


A method to get cursor coordinates, button state, and keyboard map. 

A method to reserve space on the virtual screen for windows. 

A method to lock the entire virtual screen for out-of-window drawing. 

An HFS server. 

A method to construct the low memory that applications expect to see: VCB queue, FCB 
table, WDCB table, etc. 


yp re 
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Coping with Dr. Strange Biue 
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Why Read This? 


This document is an introduction to the capabilities and features of the Blue Adapter N&C 
extensions and their ramifications for non-Pink N&C products. It is intended that this 
document provoke discussions about the services that must be provided by the Blue Adapter to 
support key, existing N&C products that will not be rewritten for the first Pink release and 
hopefully to head-off any design/implementation decisions that would doom a key product to 
not work under the Blue Adapter, and thus, under Pink. As new N&C products are planned and 
designed, it is important that consideration be given as to how the product functionality can be 
provided under Pink. . 


What is Dr. StrangeBlue? 


ie Adapter effort of Pink (see precec 
ivided into two teams: one: om system 
environment and a seca 
and communication fx 


Dr. StrangeBlue is the 
document). The actua 
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the gradual migration of all N&C products to native Pink. In theory, all of the MCP-based 
products, Comm Toolbox tools, and actual network applications should run unmodified on the 
Blue Adapter; that leaves reimplementation of only driver-level code, which is a substantial 
effort in its own right. 


In practice, the transition won’t be quite that easy. The Blue Adapter will support the defined 
Inside Macintosh interfaces. Unfortunately, to get many N&C products to function at all or 
with acceptable performance, it is necessary to use system-level knowledge that is not 
standardized in Inside Macintosh and that heavily depends on the actual underlying Blue 
implementation. One of the biggest challenges of the Blue Adapter effort will be to find those 
hidden assumptions and to accurately emulate the implementation of Blue. 
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Details...Details... 


The exact details of the Blue functions (documented otherwise) faithfully emulated in the Blue 
Adapter will evolve as the Blue Adapter code is completed. At this early stage, it is 
impossible to give a definitive definition for what will and won’t work under the Blue 
Adapter. This section provides the current knowledge about how to code a product to be binary 
compatible with the Blue Adapter. 


What absolutely won’t work! 


Pink operates in 32-bit addressing mode.! All code that works under the Blue Adapter must be 
32-bit clean. Luckily, most products will be tested for 32-bit cleanliness as a part of moving to 
System 7.0. 


have direct access to any h 
‘ferrupts. All code that dire 


Code running under 
(such as slot space) a 
hardware must be 


What ma work??? 


System 7.0 Finde: 
one Finder, the Pink Find 


the Tool Managers is yet to be determined. Tools that adhere to the published interfaces 
should work unchanged. 


The A/Rose IPC manager will be usable from within the Blue Adapter. Software that directly 
accesses NuBus card memory without going though A/Rose will not work. 


The VBL manager will be emulated for applications that require timing. 


lEarly Pink systems attempted to run in both 24-bit and 32-bit mode. The time 
it took the PMMU to switch between modes at interrupt level caused the 
LocalTalk SCC to overrun with resulting loss of AppleTalk packets. 
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Functional Overview 


Function/Interface Call | Calls Supported . 


.MPP Driver writeDDP, closeSkt, openSkt, | Full AppleTalk support 
loadNBP, confirmName, except for direct access to 
lookupName, removeName, LocalTalk LAP (i.e., 
registerName, killNBP, writeLAP, attachPH, 
setSelfSend, unloadNBP detachPH). 


.ATP Driver relRspCB, closeATPSkt, 
nse, sendResponse, 


Soper A TPSkt, 


eataOcteterete 


M5esSsiOn; cioseSession, 
abortOS, getParms, closeAll, 
userWrite, userCommand, 
getStatus 


.XPP Driver '5 are supported. 


ADSP Driver 


LAP Manager — 


-ENET Driver 


.ipp Driver (MacTCP) 


ee 
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Function/ Interface Call Calls Supported 


Serial Driver Depends on Pink support for 
SCC handling & mode 
Comm Toolbox Manager Scope of CTB manager 
changes unknown at this time. 


control. 
Serial Tool Comm Toolbox connection 
tools should work under the 
Blue Adapter without 


ADSP Tool 


MacTCP Tool 


LAT Tool 


Open Issues 


1) The Blue Adapter file system 
client code for efficiency. Otherwise, the: 
would then be mapped back into HFS-A 


2) Emulati 
Pink with 


software 


ifications; is thi 
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Jane 


An Advanced Word Processor 
by Margie Kaptanoglu, Ann Greyson, Jeff Hokit 


Overview 


~ 


Jane is an easy-to-use advanced word processor designed to address the writing needs of professional 

writers and academicians. Two examples in the former category of writer include novelists and technical 
writers; some examples of the latter area student writing his/her dissertation or a professor producing a 
work of research. The focus « er of the computer to facilitate the wri 
or in other words, the proc ‘a finished document. Jane apr 
lem of supporting the writ 
consists of some combina: 


persons vat some time, by an edit 
from simple stylistic changes to 
Soliciting and incorporating fee 


ies of their document an ask the ae to scribble i in the margins. Even individual EahOE Ae is not al- 
ways entirely electronic; many writers still type in a draft of their document, print it out and mark it up 
on paper, and then enter the changes on the computer. Ideally, Jane will make all aspects of producing a 
document so simple to do on a computer that the use of paper will be limited to printing out the final ver- 
sion of the document. There are many ways in which the tasks writers have been performing on paper 
can be made much easier by a computer, and we list some examples of how Jane will do this below: 


¢ Editing capabilities such as delete, insert, cut and paste have always made editing simpler on 
a computer than on paper. Through the use of direct manipulation, Jane makes editing even 
easier by allowing users to simply grab a selection of text and move it anywhere in the docu- 
ment. 

¢ Paper users have always been able to look at non-consecutive pages of a document at the 
same time (and as many pages as they like). This is an area in which word processors have 
traditionally fallen short. Jane provides this functionality by allowing the user to open as 
many views of a document (or of many documents) as desired. Jane also lets the user Zoom 
in to, or out from, a document. Zooming in allows the user to read or edit some text at a larg- 


a a i at eo a ee 
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er point size than it is written in; this is useful since text formatted in a small point size is 
often difficult to read on the monitor. Zooming out lets the reader view a larger portion of 
the document at one time. 

¢ Tasks which are extremely tedious on paper, such as indeces, glossaries, bibliographies, 
footnotes, endnotes, headers, footers, tables of contents, page-numbering, and references, are 
generated and maintained automatically within Jane. We are aware that many of these fea- 
tures are currently offered by other word processors, but in Jane we will make their usage 
more consistent and easy to learn. We also plan to automate such features as indeces and ta- 
bles of contents to a greater degree than existing word processors have done. 

¢ Co-authoring requires that it be possible to break a document into sections which each author 
can work on separately. Most word processors require that a document be a single file in 
order to be able to generate page numbers, table of contents, and so on. Jane allows the user 
to break up a document into separate units (which could be considered chapters or sections, 
for example), while still maintaining knowledge of the document as a whole. This makes au- 

ment-wide features possible across secti 

vantages of writing the docume 

of the document, rather tha 

uthor to automatically 


aifications made by 


he document to enter 
aching a note to it. The 
low him/her to modify or 
paper. The author’s job is 
inthe imargin or in sepa- 


: gained Over paper by allowing 
he document itself, by making a selection 


not to provide highly sophisticated page-la 
and well-focused application, and our cons 
creating a full-featured word processor, as opp 


program. 


Motivatior 


This is the section which answers the question “Why a word processor for Pink?” Our answers are: 


¢ Writing is one of the most basic functions performed on a computer, and therefore any new 
system needs a word processor. 

e Word processing is a major area in which we can show what is better about Pink. Annotation 
and collaboration are two areas which have barely been touched by existing word processors. 
In supplying these features, Jane will show off some of the best of Pink and set an example 
for future Pink applications to follow. 

¢ The successful development of a “real” (i.e., shippable) application on the Pink platform will 
verify that Pink is indeed a viable system. 
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User Interface 


As stated in the overview, one of the major goals of Jane is to simplify the writing process by making the 
word processor easier to use. To accomplish this goal, some improvements need to be made to the user 
interface model. An example of this is our use of direct manipulation text, described below. Moreover, 
entirely new interface designs are necessary for features which have not been offered before, such as the 
book metaphor, collaboration, and all types of linking. Designs for some of these new features, which 
will affect all applications, not just Jane, are currently being investigated by the Pink Human Interface 
team, as well as by the Jane team. See future versions of this ERS and the Human Interface Architecture 
for descriptions of how Pink plans to solve these problems. 


Guidelines 


We have come up witha help enhance the ease-of maintain consis- 


tency across Pink applic 


Direct Manipulation Te 


One important way in which we hope to mak 
direct manipulati a This is an extension : hic 
objects on the M i ise is 


Direct manipulation. a} 
handle appears on the left side of the eae The v user may then click on this handle, and while hold- 
ing down the mouse, drag the selection to a new location within the text. When the mouse is released, 
the dragged text is inserted at the new location. While the text is being dragged, a small caret is shown 
underneath the selection, indicating where the selection will be inserted if it is dropped. When the select- 
ed text is first “picked up”, a blank area is left where it was. No reformatting of the text occurs until the 
selection is released. The text may be dropped in the blank area, in which case it is simply restored to its 
original location. When the text selection is longer than twenty characters, the selection is shown truncat- 
ed when it is picked up, with an ellipses at the end. The selection is drawn opaque, with highlighting, 
and with a see-through shadow. This gives the text the appearance of having been picked up; it looks as 
though it’s hovering slightly above the page. A sample is shown on the next page. The word “matter” is 
the selection being dragged. 
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It's not a question of where he grips it, 
it’s a simple fvweight-ratias ... 
a five-ounce tA. jnot hold a 

one-pound coconut. Look! To maintain a 


Program Description — 


What follows is a partial description of the basic features of Jane. The motivation for our design choices 
has been to select the methods which will best support the writing process as described in our overview, 
while still ensuring that th -This section is by no means comple 

rently involved in coming: or Jane, which will be outline 
of the ERS. 


The Text 


Jane supports all the his means that users can 
create beautiful text; 
power given them 


the near future. 


ne, however, is 
eep the interfa 


two and three and o page vd nine at the same time. One v view could. >t pap 
other could be side-by-side pages; one could be zoomed in, the other could be at 100%. Editing changes 
made on pages two or three which affect pages eight or nine cause the view of pages eight or nine to be 
updated as well. Updates are as smart as possible, to avoid too much screen redraw. 


Zooming in and out is supported. This includes manual zooming (zoom to 50%, 200%, etc.) as well as au- 
tomatic zooming (make this page fit within this view, for example). 


Like typical Macintosh word processors, when a document is first created the user is presented with the 


representation of a blank sheet of paper, page one. The user may immediately begin typing. As the user 
types and fills a page, subsequent pages are generated automatically. 


1. See Text, section 2.7. 
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Rulers 


Jane provides “real world” rulers, as in MacDraw II, along the top and left sides of a document. These 
rulers may be shown or hidden, as the user desires. When the mouse is held down anywhere within the 
document, its position is shown within the rulers by some small indicator (like the gray lines drawn in 
MacDraw II). These rulers will aid the user in laying out pictures, lining up columns, positioning tabs, 
and so on. These rulers do NOT contain information in them about tab and margin settings, or anything 
else, as MacWrite rulers do. 

Jane also provides something similar to MaceWrite rulers, which we will call formatting bars. These con- 
tain the tab settings, the left and right margins, paragraph indentation settings, and column settings. For- 
matting bars can be inserted ona per-line basis. All of its settings can be changed using a direct manipu- 
lation action (grabbing the margin indicator and dragging it, throwing a tab away, and so on). There will 
be an automatic way of specifying:the: ber-of:cobhumns, but there will also be column indicators: 

the formatting bar. A colu 
In this way, columns of di 


Sidebars 


Jane makes it easy fo provided for 
drawing shapes, whi mor can have 
text typed into then, 3 ; xgon. After 
the user selects one in ¢ we By de- 
fault, the surrounding text Take 3 : 
wrapping off, and make the shape s¢ 


of the frame and the fill, can be set by the 


Shapes can be selected at any time the selectios : 
drawn on top of one another, and may be opaq i 2 ;odi- 
fied with Move T 


within the shape 
other types of data): 


Shapes come with small handles at their bottom right corners. The user can grab the handle and drag it 
to another shape. This binds the two shapes in the sense that any text overflowing from the first shape 
will flow into the connected shape. A line from the bottom right corner of one shape to the top left corner 
of another is used to indicate which shapes are connected to which other shapes. 


Searching 


Search and replace functions are provided by Jane. These functions can be used for finding and replacing 
text attributes as well as for text. For example, executing a command such as “replace all selected 12 
point Monaco text with 14 point Times text’ is possible. 


The ability to leave bookmarks within the document is supported. The user can make any selection (text, 


graphics, or imported data) and “mark” it. We have not yet decided how the user will access these 
_ marks. Some possibilities include text markers as in MPW,, iconic markers shown along the scrollbar (en- 


tah a ce aa Se aa pe tg 
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abling the user to simply click an icon and jump to the marked data), and a sort of “live” table ofcontents 
in which all marks are listed as text or pictures, and the user may select from among them to go to the 
marked data. 


The user may also traverse his/her document by specifying the page number to jump to. The current 
page number and number of pages in the document are always displayed in the view. 


Linking 
Jane provides the capability to link related items ina document, or between documents. To create a link 
the user specifies its start and end (although once the link is constructed it is bi-directional). Jane under- 
stands two different kinds of links, which we will refer to as navigational links and hot links. Navigation- 
al links allow the user to select a linked item (at either end) and traverse that link to the other end. In 
other words, when a link i ing on a link icon, perhaps), another ms up 
showing the opposite end . 


Navigational links are 


| eraphies, index en- 
tries, and annotation n@ 


miple, the user selects 
ark the location of the 

ew window. The note is 

f chapter, or the end of the 

ote is then linked automati- 

s up the Notes 

aent to open 


cally to its entry 0 
page; likewise, se 
up, showing the r 


on the other end of the link, and pasting then 


Hot links are ae by ae to make the eqn 


causes the Tuffy , 4 
turn to the Finder and search for the document i in which s/he created the original chart. The user can 
now edit the chart in the Tuffy window, and then push the data to the other end of the link, so that the 


modified chart automatically replaces the older version of the chart in the Jane document. 


Links are represented by an icon, which could vary in appearance according to the type of link. We may 
want the icon to clearly differentiate between navigational links and hot links. We may also want to dif- 

ferentiate between further subclasses of links, such as the examples we gave above for navigational links. 
This an open issue which needs to be solved at a system-wide level. In Jane it is also possible to hide the 

link icons, if so desired. 
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The Book Model 


Jane supports the idea of a “book”. A book is a kind of folder containing files representing various parts 
of a document. These include the chapters or sections of the document, the table-of contents, the index, 
the bibliography, and the glossary. The advantage of maintaining separate sections is to enable different 
authors to work on the same document at the same time. In addition, the various parts of the document 
have knowledge of each other; whenever one section changes in some way that affects the document as a 
whole, the other sections are notified and updated appropriately. An example of this is automatic Peer 
numbering between sections of the document. 


Collaboration 


The collaboration model s 
users, which we refer to as 
three types. There may bé 
Authors have full editin 
please, but the contents 4 
author applies those c ay read the document 
and attach notes to it. . ents are not modified in- 
advertently. For exam Gr: o intention of changing nt contents; s/he simply 
wants to read the do ; ce n of notes. 


ifications (unless the 


Notes 


Authors, editors, and reviewers can all leave 
lecting some data (text, picture, or imported da 
created, a new window opens up in which the q rted 
at the end of the selection to which the note ref 
note, if itis not o dy. There is no limit 


(title?) field, which 
notes selectively (by doub 
written by one individual, or all notes written on a certain date, or all notes falling under a certain subject 
heading. The manner in which notes are displayed on the screen or printed is a user preference. The user 
may choose to display them in the document margin, or in individual views, or altogether in a single 
notes window. Notes may also be selectively printed,according to author, date, or subject. 


Markup 


When a document is checked out by an editor, a copy of the document is created for the editor to modify 
as s/he pleases. When the editor checks the document back in, his/her version is saved along with the 
original document. The editor's name or some other identifier is saved with the editor’s version of the 
document. When the author then checks out his/her document, s/he may also view the version created 
by the editor. In addition, the author may request Jane to automatically generate a marked up overlay to 
be viewed on top of the original document. The marked up overlay indicates changes made by the editor 
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in his/her version of the document. Deletions are shown by a cross-out line. Insertions of just a few 
characters are shown above the insertion point; larger insertions are indicated by a note icon, which can 
be opened to read the insertion. Style changes are highlighted in the editor’s highlight color. Each 
marked up overlay is color-coded. The colors are selected automatically, in order to insure that each 
editor's color is unique. This enables the author to view multiple overlays at the same time, and still be 
able to differentiate one editor from another. 


The real power of this model lies in enabling the author to selectively apply changes made by the editor 
to the original document. In other words, the author may select a change mark on an overlay and execute 
a “Do It” command. The original document is modified in the way indicated by the change mark. 
Change marks can also be applied more automatically; the author can simply execute a command to 
make all the indicated changes of a given editor. This results in the editor’s copy simply replacing the 
original document. It is also possible to apply a class of changes automatically, such as all font changes, 
for example. 


Pink “Freebies 


The Pink toolbox provides:some powerful capabilities which are availak 
of course, Jane will ta vantage of. For example, unlimited undo 
are supported by the document architecture model’. bechaeyoe 
the layout manage “ilialso:take advantage of scripting* 
ing model will be su 
scripting will be use: 


plications, and which, 
atic document versioning 
tomatically provided by 
the system-wide script- 


Jane’s success, we feel it is important for us: 
describing a possible interface for them. 


2. See CHER, section 2.2.2. 
3. See Line Layout, section 2.7.3. 
4. See Scripting, section 2.2.5. 
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Project Dependencies 


e The scope of the project needs to be kept within reasonable bounds. Jane is a very ambi- 
tious proposal for a word processor, and it may be that we are hoping to accomplish too 
much with only three people on the team. If this turns out to be the case, it may be necessary 
to trim some of the features we hope to offer. 


* Cooperation between the Jane team and other Pink groups. It is essential to the success of 
Pink that the Jane team provide feedback on every part of the Pink system which is exercised 
by Jane. Jane, in turn, cannot succeed without other groups in Pink being responsive to that 
feedback. 


Collaboration be 


:  ecifi to 
ese. Wealso 


spell-checker of th 
used for other features, 


¢ Our goal must be to ship. For J 
application as opposed to a rese 
application can be developed on 


iLcompletion of the 
tem 
vanice 3 
mum of b us how many “a minimum” is). 


witha mini- 


a Ft ae a a 
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Current Status 


We have written a prototype demonstrating some aspects of Jane using MacApp. Most importantly, this 
prototype demonstrates direct manipulation text. A selection of text may be grabbed (by a handle pro- 
vided on the left side of the selection) and dragged to a new location within thetext. This prototype has 
been user-tested to determine the feasability of direct manipulation text. Based on the results of the user- 
testing, we have decided to go ahead with the plan to implement direct manipulation text, with some 
minor changes to the interface. 


We have written a very simple prototype in Pink which allows the user to draw shapes and enter text into 
them. The most interesting thing about this prototype is that it uses CHER, the document architecture 
model. Thanks to CHER, different views of the same document can be displayed at the same time, such 
that a change (for example, a newly drawn shape) which is made in one view causes all of the document 
views to be updated to reflect the new information. Unlimited undo/redo is also sl eae by. 


Currently we are in the feature list and designin iterface. We are 
creating mnt: prototype ; e specifications for 
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By Dave Anderson and Cindy Frost 
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Introduction 


This paper is a Senses for a data graphing application to be developed on the Pink system. 
Many of the ideas embodied in this paper originated from an earlier proposal tor Tuffy written 
by Amy Goldsmith. We have attempted to integrate her ideas with our own when writing this 
proposal. 


Tuffy was inspired by Edward R. Tufte’s book The Visual Display of Quantitative Information 


(Tufte 83]. In his book, Tufte discusses the power of data graphics to reveal information and rela- 
tionships in data that would otherwise go unnoticed by the casual observer. He presents exam- 
ples of many excellent graphics, along with many graphics that provide either inadequate and 
/or inaccurate presentations of data. 


Tufte cites several sources for the lack of graphical sophistication and integrity prevalent i in data 
graphics today. Thess ive skills in graphic artists, and abtet 
prevalent among proé hics that statistical data are 
graphics are only fo 
attitudes, we believé 5 i i ‘problem with an 
application that b at j 
individuals with t 


neasures 


existing applications, we discovered that 
leidoGraph and spreadsheets, place signi 
type of data which can be plotted (e.g.m 


sdback. Tuffy can provid 
versions of currer g with a unique emphasis on data ,empow- 
ering users with little or no artistic skill to create sophisticated, accurate and aesthetically pleas- 
ing graphics. 


/ 


Goals 


The primary goal of any graphing application is to allow its users to produce alternative 
presentations of quantitative information in the form of graphs and charts. Tuffy goes beyond 
this by attempting to aid the user in producing graphs and charts which conform to Tufte’s prin- 
ciples for high quality data graphics, and in choosing the optimum presentation for a particular 
set of data. Tuffy will attempt to determine reasonable alternatives for presenting the data and 
present those to the user. The user must be able to quickly and easily compare the various pre- 
sentations to determine which is most suitable for the data. Ideally, the user will discover new 
ways of presenting the data. 
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Tuffy will not limit the user to a predefined set of graph formats, but will provide the user with a 
graph editing tool, allowing the creation of customized data graphics to best present a given data 
set. These tools must be easy enough to use that even users with little or no artistic skill can cre- 
ate graphics which are compelling, and which provide accurate, revealing presentations of the 
data. 


Tuffy’s main emphasis is on the presentation of quantitative information. Tuffy should not be 
concerned with the acquisition or manipulation of data but should be dedicated solely to the 
generation of clear and understandable data graphics. By maintaining a focus on the presenta- 
tion of the data, we believe Tuffy can provide a complete set of tools to help ensure the highest 
quality data graphics. While Tuffy should ensure that the presentation accurately reflects the : 
data, it should not be burdened with the accuracy of the data itself. This can be better left to the 
applications with intimate knowledge of the data being dealt with. 


Our charter is not only to create a eer epEeaton but also to help shape the Pink system and 

provide verification thatit sment for applications. Because of thi “ar f 
suing design and imp s which are well defined eve 
significant areas suc 
the best interest of tt 
Pink, rather than c C 
tion. 


[t is our conter 
tools, each exéeling: a! 
dependently, these applicati 
the user as an integrated whole, sig 
and most other significant application 
can be split into “lightweight” applicaticz 
the data they act on. : 


The first and 
and data gf: 
enter data’ 
of that dat 
ing the data en eparate application will maintain'the f 
presentation and will allow the replacement of the data entry application with more sophisticated 
spreadsheet or statistics applications in the future. It will also provide the added benefit of im- 
posing a design which incorporates adequate support for data sharing between applications, 
proving the validity of the concept for Tuffy, and Pink applications in general. 


We also intend to follow this philosophy when developing the graphing capabilities of Tuffy. 
For example, graph format editing capabilities could be viewed as a tool separate from the the 
tool which manages multiple graph views ona document. Again the interaction between the two 
comes from sharing a common document model. [n this case, the graph format description 
model. Users will be allowed to work with the graphing tools which are of interest to them with- 
out additional clutter produced by unused tools. This split will also allow for the easy replace- 
ment of individual tools, such as replacing a simplistic drawing tool with a more powerful one. 


This is the direction we intend to take with Tuffy and believe it is a direction worth considering 
for all Pink applications. The realization of sucha philosophy requires powerful tools for the 
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sharing of information between applications. We are relying on the Pink Toolbox to supply such 
tools. 


Capabilities 


In this section we present the capabilities which Tuffy must provide in order to accomplish the 
above stated goals. Tuffy must provide support for producing a set of standard data graphics as 

well as custom graphics defined by the user. At all times Tuffy must provide adequate feedback 
on the quality of the graphic being created. Tuffy will allow multiple simultaneous views on the 
same data to allow easy comparison of the different graph formats, aiding the user in choosing 
the format which best presents the data. 


Graphs will be composed from a set of graphing elements which include data plots, data pone 
axes, grids, legends, tex fields;-et affy-wilkmrovide standard elements for each of th 
types and will also elements. Direct manipulation 
elements will be an allowing users to quickly < 
standard and custo 


Documen 

All of the data p be provided by oth 

tion may have y.to provide dat 

links provide Pink will be Tuffy 
will need to ri sthe links 


data points. 


Graph Views 


ges the user witha vi 


very quick and simple task allowing the user to easily compare different graphs of the same data. 
Providing a good metaphor for handling multiple views on the data will be important. It must be 
made clear to the user where the real data actually exists( e.g the difference between and docu- 
ment window and a view window must be clear ). 


View Control 


Graph size and view size are independent. The Graph may extend horizontally and vertically 
beyond the extent of the view with support for scrolling. The view may be zoomed in for de- 
tailed work and zoomed out to gain perspective ona large graph. 


View Composition 
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Graph views are composed of a collection of graphing elements. A simple line graph, for exam- 
ple, could be composed of a line plot, an X axis, Y axis, legend and text labels. A single view 
may contain multiple instances of a single element type. For example, several Y variables could 
be plotted in a line graph simply by including an individual Y plot for each variable in the graph. 
Additionally, an individual Y axis for each variable could be included to allow different ranges 
for each variable (similar to the double-Y plots found in some packages). Additional text 
elements could be added, etc. 


View Gallery 


A gallery of standard graph views will be provided. These will include, at a minimum, 2D scat- 
ter, line, area, bar, column and pie and 3D scatter, line, column and bar. In addition new custom 
views may be created by the user and added to the perme! of standard views. The ee could 
be presented to the uss 
for plotting. With T 
his own from the gré 
stationery and distri 
mats to authors to. 


allow a journal publisheé: Bute graph for- 


mM an article. 


Direct Manipul 


The graph vie 
point’ s value y 
ing. Inanyc 
point after the value has § 
For very dense data, or for gra ag- 
nifying glass cursor will be provid : 
point. Additionally, this magnified vi 
lected data point, making direct manipu 


ipulation of data 
ws containing th 


Direct manipulation will not be limited 


where high aé 


Backgrounds 


Graph backgrounds may be any graphic the user desires and may in fact be multiple graphics 
overlayed. A typical background would be a map over which various data points or paths mav 
be plotted. 


Data Plots 


Tuffy will provide all of the standard types of plots found in existing applications along with sev- 
eral new ones unique to Tuffy. Basic 2D plots types include scatter, line, area, bar, column, area 
and box-plots. Additional 2D plots will exist for plotting additional dimensions to the data. 
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These include intensity varied and labeled plot points. As many plots as desired may be over- 
layed ona single graph simply by including additional plot elements for the graph. 


Tuffy will take advantage of the 3D graphics capabilities provided by Albert, to provide 3D scat- 
ter, line and column graphs. Allowing various viewpoints and perspectives on the 3D graphs 
should be made straight-forward by Albert. Good methods will need to be developed for user 
manipulation of 3D views. The methods developed should be common to all Pink applications. 
A likely candidate is Michael Chen’s virtual sphere controller. 


NOTE: We need to consider plots of both discrete and continuous data. Plottng continuous functions may 
provide support for the curve-fitting functions found in other applications today. 


Plotting Elements 


Individual data poi fements in- 


clude circles, squar FS, ple wedges, etc. 3D ob re spheres 
and cubes will als 5 nal dimensions 
of the data by allo “datave ‘ore color or shape 
Tuffy will make very limi i id thi bration associated with 


ams to be used as 


data point. 


Axes 


Graph axes are composed of several indi 
labels. Each of the elements comprising ¢ 3 t . & 
lation of these.elements will be provided: 


it represents are ceponaea (e.g. if the total X domain of a graph is (0, 100) the axis range 
could be limited to the actual range of the data points, say (6 ,88) ). Limiting the length of the axis 
line to the range for the data provides additional information about the data (minimum and max- 
imum values), thereby improving the data-ink ratio. See p149[Tutfte 83}. 


Tick Marks 


Axis tick marks may be any of the elements used for plotting data points. Tuffy will provide 
major and minor tick marks with major tick marks tied to the axis labels. The use of the plotting 
elements for tick marks will allow additional dimensions of the data to be presented as variations 
in tick marks are well as data points. An example of this can be seen on p44 {Tufte 83}. 
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Tick marks may be spaced at even intervals, logarithmic intervals, or they can follow the actual 
data points. Tick marks defined as the latter, along with the lack of an axis line, would create the 
distribution axis of Tufte’s dash-dot-dash plot on p133 (Tufte 83}. 


Labels 


Axis labels will be standard text objects which will allow for wrapping of individual labels. 
Their range and increment may be generated automatically by Tuffy or specified by the user. 


. 


Grids 


Grids provide the same position options associated with axis tick marks allowing opeCne at even 
or logarithmic intervals;:e sahened-with:data:poimts. aun rnes grid lines may b u, 


tts, sizes and styles will 
— text to follow a line 


data sets (indicated by a low data-denst 
Day could allow the creation of ae t 


We are currently hich of the capabilities provided by ¢ C cs applica- 
tions could be provided by a separate Pink statistics application (or perhaps as part of a spread- 
sheet or other program), and which capabilities are so closely tied to the plotting of the data that 
they must be contained in Tuffy itself. For example, can curve fitting be supported by Tuffy 
without building in specific curve-fit functions? We will probably at least need to provide sup- 
port for error bars and the indication of mean value and standard deviation for data sets. 


Drawing Tools 


A minimal set of drawing tools will be included to allow the user to add text and basic 2D and 3D 
geometric shapes to the data graphics. Complex drawings can be imported from more powertul 
drawing applications to be used as backgrounds, data points or adornments to the graph. 
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Graphing Tools 


A set of graphing tools will be included to allow the user to select, add, delete and manipulate the 
graphing elements provided by Tuffy. This includes direct manipulation of the data points 
themselves. - 


Graphic Databases (maps) 


Tuffy will support graphic databases which can define collections of graphical objects for which 
data values may be used to control the shade, shape or color of each object. An example of a 
graphic for which this applies is on pp17-19{Tufte 83}. This graphic presents cancer rates for all 
counties in the United States as gray shades for the counties on a U.S. map. 


wing the same 
combination of v me. Tuffy will pro- 
vide support for dition, Tuffy will allow 
animation of a itovid ng variable while view- 
imati ences to 


Printing 


Tuffy will support printing of multiple gi 
mal page layout capabilities to allow the 


User 


Tuffy will provid e user on the quality of the graphic ~ A small sta- 
tus window will be available at all times with more detailed information available at the users re- 
quest. The measures are those presented by Tufte in his “Theory on Data Graphics”. It would be 
desirable to present the measures for each of a group of graphs to allow the user to easily com- 
pare between them. Perhaps 


Data-ink ratio 


This is the simple ratio of ink used to represent data to the total ink used to print the graphic. It 
can be used to aid users in following Tufte’s principle of data-ink maximization. Tufte suggests 
that maximizing the data ink ratio is beneficial to all quantitative graphics. Tuffy will provide the 
user with the value of the data ink ratio for a graphic as well as ranges which are considered 
acceptable. Additionally Tuffy will highlight redundant data-ink and non data-ink to make it 
easier for the user to identify areas of the graphic which may be removed without loss of infor- 
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mation. 


Data Density 


The data density is the number of data points per unit areaina graphic. Tufte suggests that 
many graphics are way too sparse and can be shrunk considerably to improve the data density, 
leaving room for other information on the page.Tuffy will provide this ratio for a graphic along 
with ranges indicating whether graphics are too sparse, acceptable or too dense. Tuffy could also 
suggest a size for the graphic which provides an optimal data density. - 


Graphic Proportions 


This is the simple rati 
graphic proportions i 
gle is approximatel 
more aesthetically 
of acceptability. 


ectan- 
mM found to be 
ong with ranges 


e. The width:height ratio for.thé 
Pproach these proportio 
‘the proportions for a, 


Human 


In this section ACE : Hide: 
necessary to ; 
line, listing the etemen: 
which we have begun study. 


Numeric Data entry 


will be supported th 


Editing of column labels ; 
Entry data values and categories text directly into spreadsheet cells 

Specify units and display formats for column data. This will likely be accomplish through a 
dialog box brought up by perhaps double-clicking the column header. 

Control the display width of columns by dragging column separator lines. 

Selection of columns 

Multi-cell selection including noncontiguous cell 

Delete, cut, copy and paste of cell selections 

Hypertext links between cells 

Eternal undo of commands 

Warm links to data in other application documents 


Variable and Graph Format Selection 


Select variables for plotting (from spreadsheet or other graph) 
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Select graph format for plotting from gallery 

Associate variables with plots 

Determination of graph format alternatives and the presentation of those alternatives 
Data Variable/Graph Variable associations (choosing variables for X, Y. etc} 


Graph Format Determination from Document Data 


Tuffy will attempt to determine reasonable graph formats for the selected document data. Some 
of the criteria which will be used to make this determination are as follows: . 
Variable count . 
Variable range 
Data point count 
Variable type or units 


Graph Views 


Tuffy will support m 
tential screen clutte 
for collecting and m 
has a single docum 
for that documen 
dow. The icons c 
and comparison ¢ 
dows to indicat 
operation than 4 


Pa mechanicin 
‘a design which 
h formats selected 
played in the win- 
Swing manipulation 
andard document win- 
ar ter weight 


The graph views when oper 
zooming and scrolling operati 
graphs. 


Graph quality measurements 


Axis control 


Select axis type (log, semi-log, distribution, quartile) 
Set ranges 
Set increments 
Select element for tick marks 
Attach variable to tick mark elements 
Select grid types 
Attach to specific plot 
Plotting element control 
Marker style selection 
Marker color selection 
Attach variables to plotting element attributes, e.g. shade or color 
Specification of overlay handling 
Direct manipulation of data 
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View detail information on data point 
Adjust data point directly 
Add new data points 
Manipulation of other graph elements such as those created by the user 


Graph Format Creation 


Standard and Custom graph element parts bins (similar to Constructor in HOOPS) 
Adding elements to graph . 

Connecting elements such as plots and axes . 
Customizing elements and saving in custom parts bin 

Creation of stationery to allow reuse of graph formats 


Printing/Saving 


Place and size gr; 
Save document 


Issues 


Where will the data 8ts:come. xist which will provide 
data to Tuffy 


We need to de 


Can we take advantage of Bjorn’s ¢ 
labels to align vertically with their corr: 
overlapping data points are plotted. 


e for this project we need to determi ich of the capa- 


bilities must be faduded to create a “compelling” application. 
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Motivation 


What is h@ps? 


Tomorrow ts the most important thing in life. Comes into us at midnight very clean. 
It’s perfect when it arrives and puts itself in our hands. It hopes we've learned 


_ something from yesterday. 
- John Wayne 
Pink hoops i is anew programming environment for the Pink Macintosh. a is de- 
: from. ch.to.be an integrated extension of the Pink toal 
Programming 
‘inten to pee 
Environment Macintosh provided 


accommo- 
is part of 


Features 


rated interface building 
On-line documentation 
« Multiple fonts, styles, graphics 


Initial Clients The primary clients of hoops are Apple internal system developers and Pink 
application developers. Because of the object-oriented nature of the Pink tool- 
box, the needs of these groups are in many cases closer than in the past. 
Secondary clients include any other internal or external programmers develop- 
ing for the Pink environment. 


Host ae = pas built ee gee adie integrated ee the Pink sas a is 
: esigned to be portable to different hardware platforms running the Pink sys- 
Architectures ee 
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Hardware In addition to the Pink minimum hardware configuration, hoops is expected to 
Requirements require no less than: 


« Memory - 4 MB. 
a Disk space - 40 MB. 
a Screen size - 12” diagonal. 


Sg Pee ee 
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Strategic 
Significance 


Limitations of 
Present Tools 
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Why haps? 


..a winning strategy is like a pound balanced against an ounce.. 
- Sun Tzu 


The purpose of hoops and Pink is to ensure that the next generation of innova 
tive software gets developed on Apple computers, by providing a platform so 
attractive that developers will choose us instead of our competition. Pink pro- 
vides the foundation for innovative software; hoops provides the tools to facili- 


‘tate its creation. Both are needed to create a programming environment that 


will attract the developers needed for our success. 


For some five years Apple has enjoyed a significant strategic advantage: the 
chk Ave pe : +See my BS ) : t: : : 


CAOPe 
fig to program. It hada 
Oth of which enabled the 


have been in the position of catching: the last five years. Well, 
hey’re catching up, and in some ca 


Macintosh applications:i§ 
velopment tools. Pink addre 
addresses the limitations of the developm 


A basic premise behind the Macintosh toolbox was that, by supplying a power- 
ful integrated library, we would provide our developers with the leverage nec- 
essary to create great applications. This principle was further extended by 
MacApp, and will be carried to unprecedented lengths by the Pink toolbox. 
There is, however, a potential downside in this wealth of available power. In 
order for developers to use the appropriate pieces of Pink toolbox functional- 
ity, they must be able to find them and easily learn how to use them. 


In fact, programming a Macintosh has always been considered a difficult task, 
compared with the more traditional environments on our competitor’s ma- 
chines. Part of the difficulty has been the amount of information that is needed 
before you start. Inside Macintosh has many chapters, all of which seem to as- 
sume that all other chapters have been read. For a printed document, Inside 
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Programming 
for Humans 


Macintosh is mostly very good. It is the printed medium itself that is inade- 
_quate to the task. 


Many other programmer tools are based on program representations that are 
essentially electronic paper. These representations inherit many of the prob- 
lems of their printed ancestors, including poor cross-referencing and naviga- 
tion aids. hoops must provide much more powerful and direct data access be- 
cause Pink will be an order of magnitude larger than the original Macintosh. 
hoops addresses these needs by providing tools to manage and navigate all the 
data associated with a programming project, including documentation, source 
and resources. Furthermore, object-oriented programming imposes unique 
representational and navigational demands on a development environment. 
hoops is designed to meet those demands. 


d fine tuning. 
at once, rather 


erms, or 


principles, of direct manz 
gnition rather than recall, th 


our other end users. 


The needs of the individual are placed very high in the order of implementa- 
tion of hoops, because if we do not attract individuals, and enable them to learn 
the new Pink system, we will almost certainly fail to attract larger groups. 
When Pink first ships, Apple will be in a position much like when the 
Macintosh first appeared. Almost none of our outside developers will have 


aie This is in contrast to traditional environments which often have ways of perform- 
ing actions that are more for the convenience of the tools in the environment than 
for the programmer, e.g. ordering program elements in such a way as to allow 
single pass compilers. This was often necessary because these methods evolved 
in times when ees resources available for the individual programmer were much 


poorer. 
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Testing the P 
Architecture. 
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yond the capabilities of existing tools. 


knowledge of, or experience with this totally new system, and one of our first 
priorities must be to attract and educate them. hoops will play an important 
part in the success of this approach. 


hoops provides the means to make the Pink toolbox accessible and comprehen- 
sible, and allows programmers to apply the same organizational techniques to 
their own programs. Developers will benefit because programs of the com- 
plexity of current applications will be more easily written, understood, and 
maintained. Also, hoops will make possible programs whose creation is be- 


~ 


Asa program gets large, the development environment can significantly im- 
pact an individual's ability to deal with it. Innovative software comes from in- 


novative e individuals, even when these individuals are working in teams. We 


-individuals with the ability to expre 


cale test, but... 


ily true test of a new software 
will not only add to the appli- 
ways beyond those 
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Design Principles 


Conceptual Our life is frittered away by detail... Simplify, simplify 
Simplicity - Henry David Thoreau 

Rather than appearing as a disparate collection of tools tacked on after the 

event, hoops will be a natural extension of the Pink system and an exemplary 

Pink application. hoops unifies and simplifies program components, while 

presenting a coherent unified face. ; 
Efficiency The world is a dirty place but I wouldn't want to dust it. 

- apologies to Steven Wright 
it helps programmers. Action 
Unobtrusiveness 
Be ey Gas *. . ; ¢ B rt of 
Direct : Remember: No matter wi 
Manipulation 
ous 

Recognition emory is the thing you forget with. 
Versus Recall - Alexander Chase 

Humans can recognize a far greater body of knowledge than they can directly 

recall. This is seen in the fact that most of us have much larger reading than 

writing vocabularies. hoops will provide electronic aids to shift the burden of 

recall from the programmer to the environment wherever possible. 
Extensibility 


One never notices what has been done; one can only see what remains to be done... 
- Marie Curie 


hoops will be built with extensibility always in mind. hoops will be a multilin- 
gual environment, so wherever possible hoops will provide general purpose 
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mechanisms that can be specialized as required. We can expect to get some 
things wrong and miss some functionality altogether, so we need to make it 
possible to correct our mistakes and repair our oversights. In addition, we 
want to make it possible for developers to exercise their ingenuity by enhanc- 
ing hoops. The key to extensibility lies in an object-oriented design and imple- 
mentation. Thus, modifying or extending hoops will involve exactly the same 
process that is used to create Pink applications. The object-oriented design will 
permit extensions ranging from simple behavior modifications to the addition 
of new tools and support for new languages. 


x 
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What haps is not 


e iA = 
It isn’t MPW Change is not made without inconvenience, even from worse to better. 
or UNIX - Richard Hooker 


hoops is not a port of MPW or UNIX development tools. The way programs 
are represented and manipulated in hoops differs fundamentally from these 
traditional environments. In order to provide an increase in representational 
power and to support an interactive, incremental hoops environment, we have 
moved away from the view of program source as undifferentiated text in a col- 
lection of files. This means that many traditional ways of doing things have 
been replaced or modified. In many cases, the old mechanisms are redundant 
or sd eaga by mechanisms that are more intelligent about the structure of a 


It isn’t All 
Things to All 
People 


ing production quia 
new users, it is not é 
ment. We hope that 


It isn’t Slow 


Fin hoops by incremental process S 
“pool of accumulated data. 


a a 
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The Foundation 


founedastion n. 1. that on which something is founded. 2. the 
basis or ground of anything. 3. the natural or prepared ground or 
base on which some structure rests. 4. the lowest division of a 
building, wall, or the like, usually of masonry and partly or whOly: 
below the surface of the ground. —Syn. 3. See base. 


The foundation of hoops consists of three parts, all of which provide an archi- 
tecture from which a diverse set of concrete features can be produced. The first 


iy = they provide an archi- 
‘ers would like. 


de components represent those parts of a 2) 
gramming language. Organizational componenea are used to arrange other 
components into user-defined groupings, so as to organize a large number of 
components. Resource components represent archived instances of objects, 
such as windows, menus, dialogs, and so on. A full description of resource 
components can be found in the “Constructor” chapter of this document. The 
others will be fully described shortly. 


2 We use “resource” for lack of a better term, so don't read too much into it. Any 
suggestions for another term? 
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Code 
Components 
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Properties 


' Components have properties. Properties are the attributes or characteristics of 


components. Examples of properties include source code, object code, and de- 
scriptions (documentation). A property can be intrinsic or derived. An intrinsic 
property is one whose value is stored as part of acomponent. A derived prop- 
erty is one that can be derived or created from the intrinsic properties of the 
component itself, or from the properties of other components. 


All components, regardless of type, have at least four properties: a description, 
a set of clients, a set of references, and a container. The description of a com- 
ponent is represented as a Pink text object and therefore capable of including 
non-textual data as permitted by the Pink text system. The clients are a set of 
references to the users of a component. The references are a set of references to 
thase.components.that.are.used by this component. The container is a.reference 
‘component. i 


mponent and prop- 
is permits se to be exter fully support the seman- 


A _Sneuane as they ai 


tion of new comps 
install new componé 
the addition of new pr 
of “named” properties: 
known to hoops (e.g., 
methods for these buil 


amed property té 


nique if desired. 


Components form a natural basis for versioning. Ideally hoops maintains 
enough information to recreate every version of every property of every com- 
ponent. However, given the limitations of disk space, the user will have to 
control the amount of information maintained, by archiving or discarding 
changes beyond a particular date. Furthermore, it may be possible to choose 
the properties for which version information is maintained. 


As stated above, code components represent those parts of a program that have 
source code and possibly object code. Code components are considered to be 
either atomic or a collection. Atomic components are the smallest program ele- 
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-selves, but ares 


ments understood by hoops, and are indivisible. Collection components pro- 
vide a means of grouping atomic components together, thus treating the group 
asa whole. Many languages have such a grouping construct; Apple Pascal ne 
the unit, and Modula-2 has the module. 


A representative set of the kinds of code components expected to ship with 
hoops is shown below: 


Atomic Collection 

constants classes re 
type definitions modules 

variables 

routines 

macros 


Atomic Code Components 


obvious, as they map to the 
miming sat en However, as 
hoops: 


e purpose of the atomic compone : 


defined within 
this also means 


Collection Code Components 


There are two kinds of collection components: classes and modules. All atomic 
code components (except the file) reside in either a class or a module. A class 
contains only those components defined to be part of that class (i.e., its data 
members and member functions). A module contains a set of related, non-ob- 
ject-oriented code. Like the members of a class, the components of a module 
can be designated as public or private with respect to the module. This leads 

to an interface for the module, much like one would create with a header file in 
a conventional environment. As was the case for atomic components, it may be 
useful to define additional kinds of collection components as new languages 


3. For a definition of C++ scoping terminology, see Section 3.9 of C++ Primer by 
Stanley B. Lippman. 
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are added to hoops. For example, a unit component might be added to more 


fully support Apple Pascal. 


The File Component 


The File component deserves additional explanation. It represents a stream of 
text, like an MPW text file. It is atomic and therefore indivisible. Like other 
atomic components, hoops does not maintain any knowledge of the contents.of 
a file.4 


The basis of components, of course, is to do away with text files as the means of 
representing programs. Both the class and module component effectively re- 
move their components from the lexical realm of a text file. While this certainly 


aces for another), there ar 
gy be convenient. Furthe 


sin a “quick and 
om other 


ly, we do not plan more 


In addition to tho 


The source code for the component's implementation, excluding its interface or 
signature. This applies primarily to routines. 


Object code 


The unlinked object code for the component. There is the need to maintain 
object code for different build configurations (e.g., production, debug, opti- 
mized, non-optimized, etc). 


4. The expected capabilities of files are similar to those for MPW text files. 
oS: An example may be the description of “generic classes” in section 7.3.5 of The 
C++ Programming Language by Bjarne Stroustrup. 
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Container 


The component’s container, for scoping purposes. For atomic components 
(other than a file) the container is either a module or a class.® 


Public/Private 


Whether or not the component is private to the module or class in which it is 
defined. In a module, a private component is equivalent to a static function, or 
any other declaration that is not included in a header file. A public component 
is a non-static function, or other component whose interface is included ina 
header file. In a class, the public/private/ protected attribute of a member 
function or data member is as defined in the C++ class. 


ponents into user- 


Organizationa iser- 
omponents: projects 
Components ion associated with con- 


pplication, a library, a 
eby the operating system. 


structing a Pink program. A program nt. 
driver, or any other executable entity; 


DataSets... 


(}) Data Elements 
a" [C| TtuffyDocument 
[q) TValuelterator 
1D} Views... [) Spreadsheet... 
{}} Files... 

(2) Application... 


Figure 1. The structural decomposition of an application. 


6. A file cannot be the container of another component because the file itself is an 
atomic component. 


& Registered /Restricted ha@ps March 15, 1990 3.5-13 


Because libraries may contain other libraries, a hierarchical structure of a pro- 
gram is possible. An example is shown in Figure 1 above. It shows a possible 


organization of SmallTuffy, the PinkMania sample application. The) 
symbols represent libraries. In this example, the Tuffy application itself is 
separated into five libraries: Graphic Elements, Data Elements, Views, Files, 
and Application. The Pink Interface library, shown as a dimmed image, 
represents a library used by Tuffy, but not actually contained in Tuffy. The 
Data Elements library has been expanded to show that it contains three 
libraries of its own. Similarly, the Cells library has been expanded to show that 
it contains five classes. Tuffy itself is an application project. Hence its symbol, 


<&, is different. 
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Presentation of Programs 


The presentation of a program is the way in which the properties of compo-. 
nents are shown to, and manipulated by the user. hoops provides an extremely 

‘ flexible way of creating a variety of presentations of a particular program or 
part thereof. It is based on a set of independent viewers that can be connected 
to each other in various ways. 


A viewer displays a property of a component. An editor is the combination of a 
viewer and one or more transformers, which are tools that change the value of a 
“component's property. A viewer has an input, which is essentially a list of 
(usually one) components. A viewer has an output, which is also a list of 
(usually one) components. The output of a viewer is typically whatever is se- 
lected in the view. The output of one viewer can serve as the input.to another 
riven a rea- 
of useful combi- 
put of another, and 


Figure 2. A sample hoops source code browser which exhibits many of the 
same characteristics as a Smalltalk system browser. 
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To show how this works, consider the browser in Figure 2 above.” The 
browser contains three panes, or rectangular areas that accept viewers. In the 


’ top-left pane is a class hierarchy viewer, showing a class hierarchy in outline 


form. Its output (the selected class) is fed to the input of the top-right pane. It 
contains an interface viewer that shows the interface of the class TLink. The 
output of the interface viewer is the selected member of the class, which is fed 
to the input of the implementation editor. In the example, the member 
function GetNext has been selected in the interface viewer: It is sent as the 
input to the implementation viewer, which in turn displays the implementation 
for GetNext. : 


hoops will, of course, come with a set of “assembled” browsers ready for use. 

However, we can neither anticipate the needs of every user, nor their personal 
styles. For eae some people like multipane browsers, while others prefer 
multiple, single pane browsers. An advantage of the scheme just described. is 
tha rs with an easy way to construct.thi 
¢ ops to different styles. 


this approach are providi h'set of viewers, 
y y ecting them together 
ons. “The hoops Human Interface” section.@ 


ling of viewers supplied with hoops, and 


s for connecting them 


Vs This window is purely fictional and may not actually appear in hoops. Any 


similarity to actual windows, living or dead, is purely coincidental. 


8. A further advantage over hardwiring the user interface is that it allows consider- 


able flexibility in the design and implementation of hoops itself. 
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The haps Object-Oriented Framework 


We're not in Kansas anymore. 
- Greyhound bus driver after crossing the state border into Oklahoma 


There are two basic ways of extending hoops. The first technique may be better 
termed “customization” rather than extension. It involves making new and 
unique combinations of an existing set of raw materials (e.g., the viewers and 
browsers supplied with hoops). In MPW this is accomplished by writing 
scripts. In hoops, this is largely accomplished by creating new browsers. (See 


‘the “Dynamic Browsers” section of this document.) 


The second kind of extension is accomplished by adding to, or modifying the 
; in other words, by adding new tools or sito the 


tool Taek be an editor, of which hoops Sart include ane implementations 
for C++ and Pascal source code. An independent tool builder could add a new 
editor by subclassing one of the hoops editor classes. Ideally, all of hoops is 

implemented in this fashion, including the compilers, linker, editors, and so on. 


To allow for a broad range of extensions, the framework will provide abstrac- 
tions for different kinds of tools, from which the programmer can produce spe- 
cific kinds of tools. Fundamentally all tools belong to one of the following 
three categories: 


9. For the purpose of this discussion, the term “tool” is used more broadly than in 
MPW, encompassing all the capabilities of hoops, including editors for example. 


haps March 15, 1990 3.5-17 


Adding New 
Tool Classes.£ 
hoops 


é Registered /Restricted 


Viewers 


' Viewers represent a view of some data, as described in the “Presentation of 


Programs” section. Viewers are generally responsible for the visual presenta- 
tion of some data, and for handling mouse clicks, selections, and other opera- 
tions that change the presentation (as opposed to the data being presented). 
For some kinds of data, there may be several viewers, each presenting a differ- 
ent view of the same data. 


Transformers 


Transformers are tools that change a property of acomponent. Transformers 
rpically used in, conjunction with viewers, though this isn’t neces 


zed and the re- 


While the Environme 
ions to hoops, it does 
ilable to hoops. To 

h 


Hetead, we would prefer’ : 

at run-time, without relinking or. 
- Fo unately, the Pink run-time system provides exactly such a feature, 
called dynamic classes, which allows classes to be added to an existing applica- 
tion at run-time. The details of dynamic classes are still undetermined, but the 
basic idea is that dynamic classes are deposited in known locations to the sys- 
tem or an application, so that they can be found by applications that need 
them. Thus, when hoops starts up it would obtain access to all of the dynamic 
classes available to it, thereby making them part of hoops. 


Given that hoops remains unchanged in this scenario, it follows that the only 
means of communication between hoops and the dynamic classes is via a pre- 
defined interface or protocol. This implies that the only kinds of extensions to 
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hoops are those permitted by the interface or protocol.’ This is one of the rea- 
sons why it is important that the Environment Framework provide a good set 
of abstractions from which a broad range of tools or components can be built. 


Once new tools and classes are made accessible to hoops, there still exists the 
problem of making them accessible to the user. A command-line interface, 
such as MPW’s, solves this problem to a great degree because the user can 
simply type in the name of a tool to invoke it. Assuming that we don’t want a 
command-line interface, we need an alternative. For viewers and editors this 
is done by using hoops’ “dynamic browser” capabilities (see “The hogps 
Human Interface” section), which permit assembly of any combination of 
editors and viewers known to hoops. For other tools, we can associate them 
with the kind of data on which they operate. For example, the Count tool 
eat on data that can be represented as a text stream. The advantage of 
roach:is that: t-sensitive manner. 
am, then the 


10. Upon initial examination, this may appear to be a difficult if not impossible task. 
However, similar mechanisms already exist on the Macintosh. For example, all 
windows and controls are implemented via “definition procedures,” permitting 
the addition of new windows and controls without changing the Window or 
Control Managers. Similarly, ResEdit has the “picker” mechanism for adding 
new resource editors to ResEdit without changing Reskdit itself. Both the 
Toolbox and ResEdit have invented a dynamic linking mechanism to suit their 
specific needs. Dynamic classes, on the other hand, are a system-wide solution 
available to all Pink applications. 
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~The s Human Interface 


No more command-line interpreters. Ever. 


This chapter describes our current thoughts on the hoops human interface. 
Clearly this section of the ERS is subject to great change. In addition to reading 
this section of the ERS, you may wish to view the hoops prototype. You should 
also bear in mind that because hoops is a Pink application, its human interface 
is directly affected by the Pink human interface currently under development. 


won't exist. Rathe 

scripts. It is inten 

Pink system-wide 
h 


‘terface can n be greatly customized to suit individual users. Additionally, 
the interface will be capable of supporting the addition of new tools (i.e., 
viewers) to hoops. 


11. Theterm “pane” is used more liberally in this document than in the Macintosh 
Human Interface Guidelines. 
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Human Interface Elements 


This section describes the fundamental elements of the hoops human interface; 
a number of which are shown in Figure 3. This is subject to change pending 
the definition of the Pink human interface. 


G Pink interface... 
Q Graphic Elements... 
Q) Data Elements... 
Q Views... 

Q Fites... 

Q Appiication... 


ae 
Sears 


aiSts Of One or 
frequently used to 


King, a browser is a spec 
: It is often referred to as 
rowse” a set of components. 


A pane is a rectangular subdivision of a browser in which a viewer is dis- 
played. A pane has three important parts: an optional icon bar (defined be- 
low) along the top; an optional vertical sidebar on the left side of the pane, in- 
dicating the kind of view displayed in it; and the content portion of the pane, 
which displays a viewer. The icon bar and vertical strip are color coded ac- 
cording to the view installed. The presence of horizontal and vertical scroll 
bars depends on the pane’s viewer. 


Viewers were discussed in the Foundation section of this document. Their 
purpose is to display a property (or properties) of a component. Viewers are 
installed in panes. A pane displays one viewer at a time. A sampling of the 
viewers is provided below. New viewers can be added to hoops by using the 
Environment Framework, as described in “The Foundation.” 
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Specific Menus 


The Icon Bar 
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The main menus are used for commands that affect the entire environment or 
project, and for generic commands that apply to most selections. Examples of 


" commands that affect the entire project might include the setting of certain op- 


tions, or opening an empty browser. Cut, Copy, Paste and Print are examples 
of generic commands. 


For any given selection in a view, there is a set of commands or operations that 
apply specifically to that selection. The set of commands or operations differs 
for each kind of selection, and includes those things that are sensible for the 
given selection. For example, the operations for a selected class might include 
spawning a class ancestry or class descendancy view, while the operations for a 
selected module would not, because the module has no relation to class hierar- 
chies. 


20 assible mechanisms for implementing selection:s Om: 


ion, which we have 
sed in our prototypes is the pop-up menu; u wish to invoke a 
lection-specific operation on the selection, its pop-up, whose con- 
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A haps Viewer Sampler 


In this section we show what a number of hoops viewers might look like, and_ 
how they might operate. This set is intended to be representative rather than 
exhaustive. For example, hoops will also provide viewers that will display in- 
formation such as “who implements method X” and “who references method 
X”, although these viewers are not shown below.” 


Program 
Organization 
Viewers 


HE Pink interface... 


(2) Graphic Elements... 
{}) DataSets... 


Spreadsheet... 


QD) Application... a 


Figure 4b. A view of the Tuffy application’s contents as a hierarchical 
structure in outline form. 


12. These examples of views are shown with “grayed out” panes in order to both 
give a context for the view and to clearly differentiate the view (the dark part) 
from its enclosing pane. In real life, the panes and their views are equally dark. 
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Purpose 


Input 
Output 


Selection Techniques 


Operations 
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Component Modification Date Modification 


TDataSet Thu, Dec 7, 1989 4:29 PM interface, Implementation 
TRowDataSet Thu, Dec 7, 1989 4:28 PM implementation 

Q) DataSets Thu, Dec 7, 1989 4:20 PM interface, description 

TRow Thu, Dec 7, 1989 4:20 PM implementation 

TScatterPlot Thu, Dec 7, 1989 3:57 PM interface, implementation 
TPlot Wed, Dec 6, 1989 12:52 PM interface, implementation 
TColumnDataSet wed, Dec 6, 1989 11:48AM implementation 
TTuttyDocument Tue, Dec 5, 1989 10:38 AM implementation a 
TValuetterator Tue, Dec 5S, 1989 10:30 AM implementation pre 


jraries, modules, 
d cli “The - modified, and al- 
abetical. The data modified and Rees y show the nodes of 
tree it ina Spanner order, and are devoi 1 


Selecting a non-leaf'n 
An insertion point cart 
contents of the Clipboa 


odes can be inserted « 
fon pom inserts the 
1 


| d outline views, double-clicking a node’s icon'éxpands or 
collapses its subtree. Node reordering within a subtree is accomplished by 
dragging the node’s icon until it appears in the the desired location with re- 
spect to other nodes in the subtree. 


A node is renamed by clicking its name and changing it directly, as one would 
change the name of a file in the Finder. 


Given a selected node, a new viewer of the same type can be spawned in a new 


~ browser, allowing browsing of the subtree whose root is the selected node. It is 


possible to search for nodes of a given name. 
Any browser capable of accepting the selected component(s) as its input can be 
opened. In that case, the selected component(s) becomes the new browser’s 


input. 
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Description 


° The Member function determines whether its parameter is contained 
Viewer 


in the collection this. Each object in this is compared to obj using the 
function testFn. Member returns the object for which testFn returned 
true; nil is retumed if no object is found. 4 


Overridden so that if the collectible (a TCell) 
has a column number that matches the 
dataset’s fColumn, and the input cell matches 
the one referred to by the dataset, return 
true. This should be more direct than 
scanning the whole collection, as Member 
may otherwise do. 


_ Figure 5. A description viewer. 


Purpose éditing of a component's: 


Input ent. (All components 


Output 
Selection 


Operations 
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Input 


Output 


The Display 


Selection Techniques 


Operations 
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version 


author modification date description 


6 Curt Thu, Dec 7,1989 4:15PM added GetOutOfHere() 
PinkMania Dave Wed, Dec 6,1989 2:32PM changed At{), HighBound()... 
Dave Wed, Dec 6, 1989 2:02PM changed Member() 

Dave Mon, Dec 4,1989 3:13PM added Member() 

Dave Fri, Dec 1, 1989 9:38 AM changed ~TRowDataSet 
Dave Tue, Nov 28,1989 1:32PM new class 


—_-NW A 


nase Na MaMa TAMA NMe MeN MAM tat ata tata t ata taATe Tata t Mahe Me AMT TAMSM Me tatate Mette M Mute B NTA E MATE tNMe tEAM MIAN Etta tate ete Me ttt NTN NE NTN tt NAMM CenG NE 


Figure 6. A modification date viewer displaying information about a 
single component’s versions. 


Selecting anywhere in the line selects that version. Multiple versions can be 
selected by dragging through multiple lines, or by extending the existing selec- 
tion. 


Any browser capable of accepting the selected componeni(s) as its input can be 
opened, in which case the selected component(s) becomes the new browser's 
input. 
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Class Ancest 


Viewer 
MKernelObject —» |C] MBaseTask —— > |C} MTask 
{c}TGraphTask 
MCollectible —>» [C] TGraphic 
Figure 7. A class ancestry viewer displaying a view of TGraphTask’s an- 
cestors. 
ancestry of a class. The an class is the set of 


Purpose 

e class is derived. For, 
ss; the display shows all the classes incl 
may appear more than once in the disple 


tarting with the input 
definition. Thus, a class 
ding on its derivation. 


Input ly single class component. 
Output 
Selection Teck 


ass or 


Operations 
such as: 


classes as if 
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Class 
Descendency 


Viewer 
TAxisx 

TAxis —>| 
TAxisY 


TMarkerRectangile 
TMarkerOval 
TGraphTask ——»}/@) TMarker ——>» TMarkerPlus 
TMarkerTriangle 
TMarkerDiamond 


TPlot == (0 TScatterP 


Figure 8. A class descendency viewer di sw of TGraphTask’s 
descendents . 


Purpose 
play 'SAGy hus, 
a class may apf on. 
(The example show 
are defined with mui 

Input 

Output 

Selection Techniqu 

Operations ected class or classes, any browser or too f accepting a 


P 
class or classes as input can be opened. Other operations are being considered 
such as: modifying the class hierarchy, deriving new classes, etc.. 


FN a at a ee 
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Interface Viewer 


Purpose 
Input 
Output 


Selection Techniques 


Operations 
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TRowDataSet ~ 
class TRowDataSet: public TDataSet 


{ 


private: 
RowNumber fRow; 


. 


public: 
TRowDataSet(TTuffyDocument’ itsDoc, RowNumber row); 
virtual ~TRowDataSet(); 


virtual MCollectible* At{ /ong index) const; 
virtual MColiectible" Member(const'MCollectibie* col) const. 


‘e'e'ee'e'e'e eels eee a e'ela eee ee alee ele ee ea eee eee ale 'a'etate 80% 


Figure 9b. An interface viewer displaying an abstract definition of the 
TRowDataSet class. 


To display and permit editing of the interface of a component. 
Any module or class component. 
Any selected component(s) in the interface. 


Any single component, or set of components can be selected from the class or 
module. 


Given a selected component or components, any browser or tool capable of ac- 
cepting the component(s) as input can be opened. 
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TRowDataSet::Member 
MCollectible’T Row DataSet::Member( const MCollectible*col) const 


RowNumber row = ((TCell*) col) -> GetRowNum(); 


MCollectible* item; 


(col -> IsEqual {itemn)) 
retum (item); 


I aaa So aD aS cn San SaaS 


9... An implementation viewer | source code for the 
Glass::Member function.; 


Any single comp 
Selected text. 


See the subsection enti 
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Object Code 
Viewer 


TRowDataSet::Member 
MCollectibie*TRowDataSet:Member( const MCoilectible*col) const | 


link a6, #SFFFS 
movem.1 d7/a3/a4,-(sp) 
movea.l $000C(a6),a4 
$0008 (a6),a3 


movea.1 


move.1 a4,~$0004 (a6) 
movea.l -$0004(a6),a0 


movea.l (a0),a0 
move.w $00B0 (a0), d0 
ext.l do 

add.1 -$0004{(a6),d0 
move.1 d0,-(sp) 
movea.l -$0004(a6),a0 
movea.l (a0),a0 
movea.1 $00B4(a0),. 
jsr (aQ) 


e disassembled object code 


Purpose 


Input re 15 a 3 € of its con- 


Output 


Selection Techniques | Undetermined 
ging purposes. 


will probably 


Debugging operations will probabt 
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Dynamic Browsers 


While hoops provides a set of “assembled” browsers, a powerful feature of 
hoops is that the user can change the layout of any browser. Furthermore, by 
saving those changes the user can modify existing kinds of browsers, or add 
entirely new kinds of browsers to the interface. This gives the interface a 
tremendous amount of flexibility and extensibility. 


The feature of hoops that allows such flexibility is the treatment of viewers and 
panes as independent entities that can be connected to each other. Ina nut- 
shell, browsers consist of one or more rectangular areas called panes, each of 
which displays a viewer, and are connected so as to “drive” each other. The 
“layout” of a browser describes the number and location of the panes, their as- 
sociated viewers, and the connections between the panes. By changing 

bro (ble to create entirely new kinds of bra 


rface addresses 


Pane Layout : y time. This is done by 
| Si or by splitting 
fault, newly 


Viewer/Pane 


Association one view at a time, th 


pane is to enable the us 


Connections > 
Between Panes 


The output of a pane can be connected to the input of another, thereby connect- 
ing panes together. This is done with a wiring tool similar to Constructor’s. 
These connections are “hot”, causing the panes to “drive” each other dynami- 
cally. When the output of one pane changes, it changes the input of the panes 
connected to it, thereby changing the data displayed in those panes. For ex- 
ample, consider a two-pane browser which connects a pane containing an 
interface viewer and a pane containing an implementation editor. By changing 
the selected component in the interface viewer, its implementation is immedi- 
ately displayed in the implementation editor. 


rn a a 
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Saving Browser 


Layouts 
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The output of one pane can be connected to the inputs of several panes, in 
which case the same input “drives” several panes. This makes it possible to 
produce different displays of the same input, all of which change when the in- 
put changes. The output of several panes can be connected to the input of a - 
single pane. This allows for viewers that combine the properties of multiple 
components (say, for a comparison tool). 


In all browsers the input to the top-left pane does not come from one of the 
other panes in the browser. Rather, its input is fixed as a result of a selection 
in another browser via a selection-specific menu, or perhaps as a cons@quence 
of executing a command. However it should be noted that this connection is 
not “hot”, unlike the inter-pane connections. This type of connection is 
demonstrated in the “User Scenario” section of this document, where a 
selection in one browser is used as the starting point for displaying data ina 


and viewers) may be 
ent changes in the lay- 
ew arrangements of panes 
rowser layout, the user 
e with no viewers or connec- 
described above, the user can 
ate viewers with those panes, 
A168 ted a new kind 


(i.e., its set of panes, con 
is allows the user to mak 
Supplied browsers, or to save; 
and viewers. For the purposes of definin 
opens an “empty” browser which ha 
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Source Code Editing 


The hoops source code browser (which consists of an interface editor and im- 


plementation editor) differs dramatically from the text editors found in most 
development environments, including MPW. A goal of the hoops editors (and 
of all views in hoops) is to produce more readable and expressive representa- 
tions of programs. 


In hoops, the text processing is much more like text processing in a word pro- 
cessor. This means there will be little or no disruption in moving documenta- 
tion between the hoops environment and a more sophisticated page layout 
program, for example. Some layout information may change but the basic 
stylistic and graphic content will be unchanged. 


tyles. Comments are phages eee: Ra 


that differentiates 
id semantics of the 


nd semantic elements 


The implementation editor is divided into different regions, as shown in Figure 
12. Across the top of the pane is the interface region. It remains anchored and 
is not affected by scrolling. The interface contains the name of the component 
being edited in large letters, the component's interface, and the component's 
description. The area below the interface region is vertically divided into two 
regions. On the left is the margin and on the nght is the main body. The di- 
viding line between these two regions can be moved by the user. The margin 
only contains comments. The margin scrolls with the main body, and marginal 
comments act as though attached to the corresponding text in the main body 
(this is described more fully Below): The main body may contain both com- 
ments and code. 
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Interface” 


Main body 


Source Code 
Style Sheets 


words could 
intelligently 


tis important to point out that the visual sty 


Marginal comment 


Description 


TRowDataSet::Member 
Set::Member{ const MCollectible’col) const 


{ “, 
RowNumber row = ((TCell*) col) -> GetRowNum(); 
MCollectible* item; 


if (row m= fRow) { 
item = At(row); 
if (col-> IsE i 


i source code is inde- 


pendent of the source code itself, and in fact is a function of viewing the code. 
Therefore, it is possible for different hoops users to view the same code, but 
with different styles. 


The set of visual styles associated with a programming language is defined in a 
style sheet. The user can define his own unique style sheet, perhaps based on a 
set of hoops-supplied style sheets. As mentioned, newly entered text remains 
as plain text and is not formatted according to the style sheet until after it has 
been successfully compiled. 
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hoops provides for three flavors of language-independent comments.!° These 
are private comment blocks, marginal comments and descriptions. (language- 
dependent comments can of course be used, but do not share the advantages of 
the language-independent comments.) | 


Private comment blocks appear interspersed with blocks of source code, as 
shown in Figure 12. They are considered to be a single, connected set of word- 
wrapped lines, and may include pictures or other information, as permitted by 
the Pink text system. Private comments are considered to be part of a compo- 
nent’s implementation, and thus are not accessible to a user unless he has ac- 
cess to the component’s implementation (i.e., source code). 


Marginal comments are confined to the margin region of the view. Each 
marginal comment is also a set of connected, word-wrapped lines, associated 
d Marginal comments are also considered to be 


in and other comments 
‘a program, and also al- 
be used as a form of on- 


defined margin" and 
lock in the main bod: 


r both can independe 


nts, both the block and marginal varieties, beha subtexts of the 
code. Marginal comments are treated for the purpose of selection as being at- 


tached to the beginning of their associated main body. Thus a selection started 


13. These are permanent comments. Temporarily commenting a section of code is 
independently accomplished using the conditional mechanism provided by 
hoops. By separating the permanent and temporary commenting facilities, it is 
possible to comment out code while still retaining its code character and associ- 
ated layout. 

14. We will use a fairly simple line splitting algorithm for code similar to ones used 
in many pretty printers, and also allow for soft returns for fine tuning. Baecker » 
shows what can be done with even a very simple algorithm. 

15. | A block usually corresponds to a statement for code, and a paragraph for com- 
ments. A block only contains one carriage return at the end, even when 
wrapped, and might have been called a ‘line’. 
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in code and carried across a comment block will select the entire comment 
block, and any marginal comments that are attached to selected blocks. A se- 
lection started inside a comment block and extended past the end of the com- 
ment will select the whole of the comment. 


Typing in the main body of the source behaves dynamically in a familiar way 
with text wrapping at margins and carriage returns starting new blocks.!® 
Block commenting is switched on and off by the same command key (which 
also inserts a carriage return, so that code and comment blocks will always 
consist of whole blocks). Marginal comments may be entered and exited using 


the mouse, or by using the arrow keys (remembering that the margins are 


treated as text at the beginning of a block). 


The treatment of comments as subtexts means that a selection may consist of 
l f code with embedded comments, but 

This means that pasting a com 
this is just the same as if the seh 
into a comment raises sar 
all be converted into 
tween comment block ocks will be lost, but what 
ve are not supporting a model 
marginal comments or drop 


any distinction 
happens if there are marginal comm 
with nested comments we can either 


ae iti ; extra text in the stream. The 


1OMment since we 


‘ke much sense 


16. Think of paragraphs in a word processor. 

17. A comment could contain text which looked like code but it would not have been 
parsed by the compiler. 

18. Text in the code does not get tokenized until the compiler has had a go at it. 

19. And in any case if the marginal comment was required it could be separately 
copied. 
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Navigation 


Gettin g From In hoops, your program consists of a collection of various components which 

Place To Place are themselves related in various ways. In the general case a component has a 
source representation that is usually text in some language. There are two 
types of navigation to consider: local and global (or inter-component versus in- 
tra-component). In a conventional file-based system local navigation corre- 
sponds roughly to navigating within a file, whereas global navigation corre- 
sponds to locating and opening files in the Finder or with standard file. 


Local navigation of a piece of flat text is done in the same way as today, using 
scrolling and searching. Of course in hoops even flat text need not be really 
flat. For example there may be hypertext links in the documentation, and pos- 
sibly outliner-like text “folding”. Remember though that the need to scroll.and 


nplished by scrolling and 
ms in a tree view or list. 


riponent in source code 
component. If there 


played in the lower Pp 
played functions cha 


References 


In addition to the use-to-definition capability, other navigation tools may be 
invoked on the selected component. These tools will build a component list 
that will be shown in a browser much like the class editor, except that the com- 
ponents listed in the top pane need not belong to the same class. The currently 
planned tools are “References to” and “Implementations of”. For example, if a 
member function is selected, the user may ask to see a list of the places where 
this member function is referenced, or a list of classes in which this member 
function is defined. The results will be shown in a component list browser that 
has two panes. The upper pane will list the answers to the query. The bottom 
pane will show the implementation of the selected item. For example, if the 
“Implementations of” tool is invoked on the selection of this->Draw(), all classes 
that implement Draw would be displayed in a component list browser. The 
items in the list can be filtered, by selecting an icon in the icon bar, to show 
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more or less information based on type compatibility, base classes, or derived 
classes. 


The state of these browsers may be saved (and probably annotated) for future 
reference. 
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User Scenario 


To help visualize the way in which hoops is used, we will go through a small 


user scenario. Suppose there has just been a major reorganization (which never 
happens at Apple) and you have been assigned to work on the Tuffy team 
(Tuffy is a charting/ graphing application under development in the Pink Ap- 
plication Group). 


You decide to browse through the program to try and understand how it all _ 
works. When you open the Tuffy project, you see a tree view of the compo- 
nents that make up the entire project (Figure 13). The tree view shows that 
Tuffy is composed of 5 libraries: Graphic Elements, Data Elements, Views, 
Files, and Application. The Tuffy project also references the Pink Interface li- 
brary. (This project organization has been created by the Rea team. nope . 
libra Vy 


Figure 13. A first level structural overview of the Tuffy application. 


Being new to the Tuffy project, you decide to explore the Data Elements 
Library, so you double-click its icon. Then you decide to look at the Cells 1i- 
brary, so you double-click its icon. Clicking Cells causes the tree view to ex- 
pand and show the contents. The Cells library contains 5 component classes, 
as shown in Figure 14. There are a number of questions you might have about 
the classes in the Cells library. For example, you might want to look at class 
definitions, examine class hierarchies, or see how the classes are used in the 
project. These (and other) operations are available from a context-sensitive 
menu. Whenever you make a selection in hoops, you may invoke a menu that 
will contain operations that are applicable to that selection. 
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+e Pink Interface... 


QD Graphic Elements... 


() DataSets... 
TDataSet 
TColumnDataSet 
{} Data Elements [} Ceils TRowDataSet 
TTuffyDocument 


TValuelterator 


D Spreadsheet... 


f application. The hierarchy 
ithi Cells library. 


class. Since 
class, TRowDa 
Color Figure 1° 
prised of a top 

TRowDataSet cl 
lected member, 
tO help you u 


is shown in 
ane of the viewer. 


At this point, since you completely understand the TRowDataSet class, you 
could make a change to Member, and then accept the change and run the pro- 
gram by clicking the run icon. This would rebuild all components in need of 
rebuilding. (If you changed only the body of Member, and not its interface, then 
only Member would need rebuilding.) Or alternatively, you could continue to 
browse using Member as the starting point. Looking at the implementation, 
you see that IsEqual is used, and you would like to know what other functions 
call IsEqual. You select lsEqual, and invoke the selection-specific menu”, which 
now lists items such as “Implementations of” and “References to”. Selecting 
“References to” brings up a browser that lists all functions that call IsEqual. 
Using this new browser, you can navigate to other classes and member 


20. ‘If you're asking yourself, “what is a selection-specific menu?”, look back on 
page 22. 
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functions. In this manner, you may explore interactions between the compo- 


nents in the entire Project. 


£} Pink Interface... 
(2) Graphic Elements... 


QD) DataSets... 
Q 
[G) TColumnDataSet 
{J Data Elements 1D) celts —- [Cc] TRowDataSet 


D Spreads 


{} Files. 


(2) Application... 


with Tuffy, you find tha 3 
faSet after all. What you want to through all 

t descriptions in the Tuffy project without opening interface or 
implementation viewers on each component. Suppose that hoops does not 
provide such a browser. You will need to construct the browser yourself. To 
do this, you could open an “empty” browser, split it into two panes, install an 
organization viewer and a description viewer, and then connect them together. 
You now have a new browser that displays the descriptions corresponding to 
the selection in the organization tree. Using this browser is no different than 
using browsers that come with hoops, and in fact could be saved as part of your 
hoops user interface. Figure 15 shows how your constructed browser might 
look after selecting the TDataSet class. 
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Program Management 


Projects 


Your Program is Inhoops, Program Management is meant to cover all aspects of data associated 


Your Project 


Projects 


Referencec 
Projects : 


@ Registered /Restricted 


with a programming project, including documentation, source, object code and 
dependency information, and how this information is used to control the build- 
‘ing of actual programs. Thus program management in hoops covers topics that 
were handled separately by Projector, make and the C preprocessor in MPW. 


A hoops project corresponds to all the information associated with 
oe ee ee Baga may be an apolication oF Ut 
ed by the operating system, ..F 
hg system file, the docum: 
s associated with the p 


nstructing 

ry other ex- 
project encom- 
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Multiple projects may be opened at th 
make use of standard editing operatié 


;and you will be able to 
€ information between pro- 


tions will refer 
reference 


References to o} 
Projects are hoo 
control. Hence 


their code is not di- 
braries are pieces of 


always remotely raterenced an 
y incorporated i in the program image. Em 
code that become physically part of the program image. 


References to shared libraries will cause rebuilds when the library interfaces 
change, but not when it’s only the library’s object code that changes. 
References to embedded libraries will also cause rebuilds when the object code 
of the library changes.” 


21. Although this may result in some context-sensitive information (such as object 
code) being lost. 

22. ‘It may also be necessary to allow mixtures of shared and embedded. 

23. Within a single project any references during any rebuild are to a specific version 


of a referenced project so rebuilds are deterministic even when circular refer- 
ences exist among projects. 
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Stationery 


hoops follows the Pink model of stationery pads as the starting point of work. 
_ This works very well, since in the Pink environment, program projects always 


start with some framework which depends on the type of program“! being 
constructed. For example, a Pink application always starts with the application 
framework. A program that conforms to the application framework but which 
does nothing is the empty application and is ultimately the starting point from 
which all applications come. This is what results when an empty application is 
“peeled off” the application stationery pad. This empty application will be 
fully documented as to how it is expected to be specialized, and serves one of 
the roles that sample applications do in today’s world.* 

The “document” created by hoops from a hoops stationery pad is alwa sa 
othing” example of the elie of 


uae eee ee ae wee ey eee 


y project can be turned into a stationery 
eatery pads will be pre 
Sach 


24. Programs are applications, libraries or any other executable entities. 

25. This does not completely do away with the idea of sample programs since these 
demonstrate ways of adding more functionality. 

26. See the next section. 
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Publishing 


Publishing Is While you are developing a program, hoops will be cooperating with the Pink 
Not Just runtime so that you don’t have to undergo a full load and dynamic relink of 

: your program” after each rebuild. Because of the way hoops accomplishes this, 
Copying and also because of the requirements of incremental compiling and linking, the 


object code of your program may not be always packed or arranged most 
optimally. Also your program as far as hoops is concerned consists of ev- 
erything, including source, that you have been using to construct it. 


What this means is that hoops needs to be able to publish a program. When this 

happens hoops will rearrange and relink all the object code, and strip out any 

private data associated with the program. Thus hoops provides an automatic 
gram for distribution. a 


certain data is pri- 
ie of your program will 
nt certain interface ele- 

c, while still keeping the 

yay wish to make some source 
showing examples of subclass- 
art of the libraries.28 Yet an- 
itionery”, from 


ou will be able to specify 


Private data : 
ample in most cases the s 


code available. For example, some 


LP 


27. | With the Pink ROM libraries for example. 

28. Weare not addressing the specifics of whether the developer interfaces to the 
Pink libraries are actually part of the ROM image or are physically separate and 
only conceptually integrated. 
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Conditionals 


In traditional environments, providing for conditional compilation is usually 
handled by written instructions to the compiler. These are in the form of some 
meta-compiler-language.”? This means that conditionals can only be known to 
the environment in a very limited way. 


hoops needs to have much more knowledge and control over conditionals in 
order to track dependencies and correctly automate the build process. : 
Furthermore the traditional approach leads to a multitude of individual solu- 
tions, one per language, in a multilanguage environment. 


hoops provides environmentally supported conditionals, via a direct manipula- 


ops this means the cor 


ble as simple icons, so t 
interface to conditional 


to the compiler, and when the condition is false it is hidden. The visibility for 
the programmer is also controllable. Each conditional can be enabled or dis- 
abled much like enabling or disabling a font style. It is possible to view the 
source with any number of conditions enabled, including all and none. 


Conditionals can have different style attributes attached to them. For example 
it may be that a common condition such as “debug” might be associated with 
red text (or background) and that when code is being viewed with “debug” en- 
abled, all the debugging code would appear as red. Figure 16 shows some 


29. _ Preprocessor instructions in the case of C and C++. 
30. “I see red, I see red, I see red” - Tim Finn. Sorry, I couldn't help myself. 
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code with conditional debugging code (unfortunately not in red), with the flags 
appearing in the margins. 


Rr 


TRowDataSet:: Member 
MCollectible’ TRowDataSet::Member( const MCollectible* col) const 


RowNumber row = col->GetRowNum(); 


MAES SAI OLA ee aeetceet 


-MCollectible" item; 


(for == fRow) { 
item = At(row); 

if (co->lsEqual(tem) 
return (item); 


aii (NIL); 


Nested 
Conditionals 


of the content 
dition settings. 


.. This may see € arrange- 


i There will be some hoops defined conditions such as debug/nodebug and 
ing New P g g 
Conditions public/private. New conditions can be added by users on a component basis, 
to cater for special needs. When a component is created it inherits the condi- 


tion state of its parent (containing) component. Conditions can be added and 
removed from components, and their state may be changed at any time. 


Switchin g You can switch the state of a condition at the component level and also globally 

Conditions at the program level. You can also affect a collection of components, for ex- 
ample, a complete library. The rule for this is that switching the state of a 
condition causes that condition to be set to the same state for all contained 
components. 
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Building Making a change to the value of a condition ona component is considered a 
Different change by the dependency mechanism, and will trigger a recompile for that 
' component on the next rebuild, provided its state has changed from the last re- 


Co nfiguratio NS build. If the state is the same as at last rebuild then that component is not re- 
compiled even if the state has been changed many times.between the two re- 
builds. 
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Configurations 


Each component may have any number of versions. A version of a component 
corresponds approximately to a saved version of.a file in a traditional system. 
A big difference is that hoops keeps all old versions (at least until you decide to 
remove them, or run out of space). A version corresponds to the state of a 
component at a particular well-defined time. 


The set of versions of components that go to make up the state of your project 


at any given time is called a configuration.’ hoops records the configuration of 


your project (usually automatically), and this can be thought of as a snapshot 
of the entire project's state at a particular point in time. 


Configuration 
Thread 4 - BSS “ co 
SS 


Aversion 3 
Figure 17. Configuration threads for different builds of an application. 


In the model being described you never directly save or delete a version of an 
arbitrary component. Rather you always deal with a configuration.** A ver- 
sion of a component is never saved without saving the configuration in which 


31. There is another broader usage of configuration, namely a set of rules that can be 
used to describe a set of configurations in the above sense. Expect terminology 
(and even concepts) to change in this area. 

32. In addition to manipulating configurations of versions, whatever Pink provides 
for versions, including the human interface for manipulating them, will be what 
you'll get in hoops. 
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Configurations 
and Branches 


Undo 
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that version exists. Of course if you change just a single component and then 


save the configuration, this is much like saving a version of the component.* 


Figure 17 shows a project that initially consists of three components (what they 
are doesn’t matter). These are version 1 of each of components A, B and C 
which together form Configuration 1 of the project. A and B are both changed 
to version 2. Configuration 2 then consists of version 2 of A and B and version 
lof C. Configuration 4 shows how it is possible to add a new component and 
revert a component to an earlier version. 

You may inspect the version history of an individual component. You may 
even choose to revert to an older version of the component. This results in a 
new configuration, but of course since configurations are saved this leaves the 
previous configuration accessible. Since you may only work on one configura- 
tion.of:your:-project-at-a:time,-the totality of configurations is a linear. list:9: 


I branch is accom- 
ig, branches is accom- 


individual actions ; f e 
checkpoint, the und¢ : 

undo chain is not the 

son is that undoing is 


33. hoops does not actually resave all the different components in your project if they 
haven’t changed. hoops does save the changed components and the configura- 
tion information that allows the correct set of versions to be accessed when re- 
quired. 

34. | Changed components have generated new versions which are recorded in the 
new configuration. 


ha@ps March 15, 1990 35-50 


Automated 
Builds 


How? 
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tion of any client that embeds any 


The Build Pirocéss 


hoops is an incremental system. The level of granularity of an increment is the 
component. This is somewhat similar to a traditional file-based system, where 
the increment size is the file. Of course hoops is also nothing like a file-based 
system, because all the information necessary to track and control dependen- 
cies is stored as an integral part of each component. hoops is not continuously 
rebuilding, but only rebuilds when asked to, exactly like a traditional system. 
The difference lies in the amount of work that occurs at rebuild time.- 


‘hoops will do its best to minimize the amount of reprocessing after any changes 


have been made in the program source or in persistent objects associated with 
the program. Thus peas the implementation of a function will result in an 


es'such as C++, 
€ amount of recompi- 

; ts encapsulation ab- 
ncretely in the resultant ob- 
sf a class will cause recompila- 
at class, even when all access 


‘ause of the nature of stati 
7 small changes may requit 
se although the langu 
stractly in the program source, it often 
ject code. For example, adding a dat 


ises there will also be a need to recompile othe: 1po 
times, for example if the change has been just to the implementation of a func- 
tion, this will not be necessary. If a change has been made to an interface of a 
component that is used elsewhere in the project, then, unless appropriate edit- 
ing changes have been made already to the component's clients, compilation 
will just result in compilation errors in the clients. 


If all changed or dependent components compile correctly, then hoops will au- 
tomatically relink any code that has changed. Once again the stored depen- 
dencies are used to minimize the amount of new work done by the linker. 


35. Of course you will usually have edited all these users anyway to avoid generat- 
ing errors. 

36. And of course inline getters and setters break encapsulation all over the place. 

37. Although, for example, hoops will know when a change is just to a comment and 
will avoid rebuilds in this case. 


haps March 15, 1990 3.5-51 


Error Reporting 


é@ Registered /Restricted 


In the best of all possible worlds you would never make mistakes, and so 
would not need to consider how to handle inconsistent and incomplete pro- 


‘jects.35 However at least some of us live in something short of utopia and so 


need to consider errors. 


You might for example reference a variable or function that does not already 
exist or is not visible from your source. You will sometimes make syntax er- 
rors, and sometimes you will forget to update clients of a function whose inter- 
face you have just changed. When you try to build a program with errors, 
hoops will mark your source at the location of the error, so that you never have 
to match errors to files and line numbers. You can think of these error markers 
as being sticky, something like markers in MPW.?? You will be able to access a 
list of all current errors and navigate directly to the location of any error. You 
will be able to validate errors individually so that they are removed from the 
list of current.errors.”. The list of current errors is completely updated after:: 


38. It has been noted that this would not actually be the best of all possible worlds, 
since it implies that we have to leave our projects in a consistent state before 
leaving work each day. 

39. | The exact appearance of error markers has yet to be determined, but you will 
have direct access to the corresponding error message (without having to match 
error ID numbers to lists in some book). 

40. Of course its up to you whether you actually correct them. 
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Importing and Exporting 


Impo rtin g hoops will provide at least a simple form of source code importation. Since . 
hoops represents programs in a database, code produced in other environments 
must be imported into the database. The easiest way to import source is to 
convert the text files into hoops file components. Since there is an exact map- 
ping froma text file to a file component (the only difference being that the file 
is an operating system object, while the component is a hoops object), it is not 
necessary to modify the source code in any way. Of course, file components 
make only limited use of many hoops features, so it would be nice to convert 
source code into program components of finer granularity. Unfortunately, this 
may not be possible for all cases without programmer modification. The 
problem is that it may not be eae to map all external source files into hoops 

iles has a 


fie form of ASCII text files. In 
syntactically correct C++, 
s.42 Some auxiliary information, 
ll beJest-in.the translation to 


It will be possible to extract code from: 
the case of C++ these files will be gu: 
é or compilation by other G: 
tures in comments, or 
h information 


Exporting 


41. In particular, certain uses of the C++ preprocessor. 
42. Assuming they support the same version of C++ we do. 
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Collaboration 


"Collaboration in the hoops context means support for team programming. We 


want teams of programmers to be able to work on the same project with hoops 
keeping track of who is changing what, while making sure that changes don’t 
get lost or out of synchronization. This certainly implies that a master version 
of a project is kept somewhere. A user may have the illusion that they are di- 
rectly accessing the information over a network but almost certainly they will 
be mostly using a local copy of the information. Sometimes they will want to 
actually disconnect from direct connection with the master copy but still con- 
tinue to work on the project remotely. 


hoops intends to make heavy use of the basic facilities in Pink to accomplish its 
aid for team Programming. This will be done ina way that should be tra 


For collection compo 
shared or inherited. Fo 
Nanas component 


Users sharing work should be able to communicate with each other. Again this 
is expected to be a system-wide Pink service and hoops will use whatever sys- 
tem model is decided upon. 


43. There may be many files in a document, or many documents ina file. The later 


case is the one most relevant to the hoops model of a programming project. 


44. —_ In Projector the level of granularity is the file, even when the unit of change is 


much smaller. This has the disadvantage of locking up much greater portions of 
a collaborative project than are necessary whenever a change is being made. 
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But Won’tIt Be We want gaining write control to be much more direct than is possible in 
Hard? . Projector for example. For example we want an individual user to gain the ad- 
: vantages of a versioning system without having to be concerned with collabo- 

ration. We also want users in shared projects to work as much as possible as 
individuals, becoming aware of the collaborative nature of their work only 
when hoops cannot automatically “do the right thing” or where explicit choices 
need to be made. It should be possible to see the lock state of a component at 
all times in a joint project shared over a network, and it should be possible to 
just start making changes in a component if it is not locked, without having to 
go through a question and answer interface. hoops should take care of locking 
_the component and transmitting the new lock state to other users. Only when 
a changed component is being “checked in” is there need for a user to be ex- 
plicitly reminded of what is occurring and to back out of changes if desired. 


ile con- 
ge and work 


I Want To Worke::::9eps.allews.collaborative work at remote machines and not just 
At Home A user is able to “check out” a. project ir 


select the components to_ 
checked in”. This will prob- 
quires too much fore-knowl- 
user to take write control of a 
soject. This then makes it possi- 
it “simultaneously”. There 
this sort. It is 


check ins” they should probab 4pdate to the latest 


ration. 


45. In Projector these two functions are mixed. 
46. Ofcourse the first user to “check in” cannot know about the other users unless 
they explicitly requested write control. 
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| Debugging _ 


Debugging in hoops is accomplished using many parts of the entire system 
rather than invoking a special debugger. Support for inspecting data, control- 
ling program flow, monitoring progress, etc., is integrated into the environ- 
ment to simplify the process. These functions are performed by pointing and 
clicking. Typing is used only for entering new data. In addition to the stan- 
dard debugging features, hoops takes advantage of its knowledge of program 
structure to support program analysis tools not typically found in other envi- 
ronments. 


I nsp ecting pee Lassie data i : “ re strength of the hoops environment. Ries 
$3 € : 


their contents. A 
sanded and contracted 
rer inspectors 


TSurrogateTask = fCurrentTask 
TLocaiSemaphore fUiSemaphore 
TView {CurrentView 
TCachedSeed fViewValid 
TUpdateRegion fUpdateRegion 


TSeed {DirtyValid 
TSeedRegion {DirtyRegion 

Boolean {Updating = true 
Boolean finterior 


Figure 18. Two inspectors: one showing the contents of the user’s stack; 
the other, the contents of an instance of a TViewPort which was referenced 
on the stack. 
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Another method uses more of a browser approach to data display (see Figure 
19). Separate panes showing stack, stack frame, source, etc., are connected to- 


gether to provide a point-and-click method of displaying the appropriate vari- 
ables. . , 


SSS Stack (ask 00-73) 


point 23 ‘ 
index 14 


Globals 
main 
WarpUsOut 
TMacrameTask::Run 


TMacrame::Step 
void TMacrame::Step() 


ngles[point] 


+ MidWidcth; 


Figure 19. A stack browser. Separate panes display the stack, stack frame 
variables, and the source context for the selected stack frame. 


Also under consideration is a technique which displays the values of scalar 
variables directly in the source adjacent to their use or declaration. Structured 
variables, such as C structs or objects, are displayed by selecting them or their 
reference in the source and then invoking a “Get Info” tool to show their values 
in a separate browser. 


Still another method uses what we’re calling a Data Connectivity Browser. This 


tool initially displays a browser with a rectangular graphic representing the 
stack. The graphic contains a vertical list of the current stack frames and can be 
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Control Flow 


Debugging 
Language 


Analysis 
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moved about and placed anywhere within the browser. A frame in the stack 
object can be double-clicked to expand in place, revealing the names and val- 


‘ues of function parameters and local variables. Variables which are pointers 


can be double-clicked to produce additional rectangular graphics in the same 
browser, displaying the contents of the objects pointed at. A line with an arrow 
is drawn from the pointers to the new graphics showing the connections. All 
new graphics thus created can also be repositioned for a more pleasing display. 
Double-clicking a pointer that is currently displaying its contents removes that 
graphic (and any that it was pointing to) from the display. Appropriate 
navigating tools such as zoom in/out are provided to assist in dealing with ~ 
large amounts of data displayed. 


The hoops environment supports various types of breakpoints, stepping, and 
tracing. Breakpoints are set by pointing at the source location where the break 
is to occur. Our proto shows setting breakpoints by selecting the line....... 


The hoops system will not provide a separate debugging language. Actions 
such as inspecting, setting breakpoints, gathering statistics, etc. are performed 
using the mouse. Occasionally, however, a more sophisticated form of debug- 
ging, such as automatically taking some special action every time a breakpoint 
is hit, is useful. To achieve this type of functionality the user will write break- 
point action code in the source language. This code is compiled independently 
of the source, but in the same context of the breakpoint and executed when the 
breakpoint is hit. 


Beyond basic debugging features, hoops provides facilities for gathering and 
displaying additional program statistics. Some items currently being consid- 
ered include the display of sizes, both source and code, frequency of execution 
information for detecting heavily used code, and instruction execution times 
over some range of source. 
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Graphical displays of system and program information will also be provided. 
Some of these displays may include team/task hierarchy diagram, heap usage, 
message traffic, performance information, etc. There are many other possibili- 
ties given the hoops architecture. . 


Even with the greatest symbolic debugging facilities, it is still necessary at 
times to deal with the program at the machine level. hoops provides displaying 
of assembly language for any function and will allow the setting of break- 
points, stepping, etc., at this level as well. Displays of registers and uninter- 
preted memory will also be possible. ‘ 


While the value of this feature is clearly understood, little work has been done 


in this area to date. Whether this capability exists in the initial release of hoops 
or not, some of the architecture to support remote debugging will be in place. 

In particular, for ease in porting to new hardware, a machine-indepx 
d for accessing memory, registers;-et 
ould also be modified to 


iformation over 


sxpected use of multitasking 
ecting which task is being 

, tracing, etc. The more diffi- 
ntrolling several executing 
perating system 
deals with these 


A major complication to debugging in 
in applications. The simpler problems 
acted upon when inspecting, settin 
include: monitoring mes 
lack stuabon, etc. Cle 


de, reusing 
eded, etc. 


pir € fi given some of the 
optimizations mentioned. One-to-many mappings are possible at times and 
hoops will need to inform the user when this is the case. Stepping though a 
routine may be ona larger than single statement granularity at times, and this 
will also have to be represented clearly. 


Inspecting the values of variables, locals in particular, can be somewhat tricky 
also. One problem is that the value of the variable may not always be available 
at any location within the routine. In these cases hoops will inform the user of 
this fact rather than give incorrect information. 


Modifying the values of variables in optimized code, again locals in particular, 
is especially problematic, and at times not possible. Unless specifically de- 
clared as volatile, the compiler “remembers” values assigned to variables and 
may use the “known” value later in the code without rereading the variable. A 
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change in that value “behind the compiler’s back” could produce erroneous 
program results. 


Fine granularity source level debugging with an optimizing compiler is gener- 
ally an unsolved problem. A number of ideas are being considered for dealing 
with these problems. Disabling optimizations during development may allevi- 
ate some of the problems. Since hoops is an incremental system, another ap- 
proach when encountering problems with the optimizer is to just add diagnos- 
tic code and recompile the function in question, especially if we are able to link 
the altered routine into the running program. 
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Constructor 


Constructor is the user interface design portion of hoops. It is used to create 
user interfaces for Pink applications (e.g. windows, menus, dialogs, alerts). In 
Pink, it provides many of the same capabilities that ResEdit and MacApp’s 
ViewEdit provide for the Blue world. Constructor provides three essential ca- 
pabilities within hoops: general resource editing, user interface layout and test- 
ing, and inter-object communication. 


Within hoops, Constructor allows the user to edit icons, internationalize text 
messages, or to edit any other Pink resource.” In addition, Constructor is 
sed f t layout. Examples include setting the on-screen location 


inally, 
by connecting together user interface 


vironment. 
tructor 


When creating an application’s user interface, no source code will be produced 
by Constructor. This avoids a major problem encountered in current prototyp- 
ing environments: once source code is generated, further changes must be 
made to either the source code or the prototype, but not both. Thus, Constructor 
should not be confused with “one-way” prototyping environments like Proto- 
typer, AppMaker or even some aspects of the NeXT™ User Interface Builder 
which convert application prototypes into source code, but cannot propagate 
source code changes back into the prototype. 


47. | Weconsciously use the term resource here as a reminder that these entities are, in 
fact, the Pink equivalent of today’s Blue resources. Pink resources are essentially 
just object instances stored on disk, or persistent objects. 
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The Foundation 


| Many of hoops’ powerful features are possible because the source code that 


makes up a project is understood to be a series of interconnected components 
and properties. hoops understands the resources (windows, dialogs, alerts, 
menus, icons, efc.) that make up an application’s user interface as a series of 
interconnected resource components and their associated properties. Resource 
components are a specialized type of hoops component designed to manage 
information about Pink resources. 


Resource Components 


Resgurcecom nents share many characteristics with the pia he 


(denoting that it can 
noting that it can send 
components represent 
sort of on-screen repre 


s connectable components to be connected together. Fir 
allows the on-screen location and appearance of user interface components to 
be modified and tested. 


The resource components designed in Constructor are eventually stored as 
persistent object resources within a fork of a finished application. Either hoops 
or, more likely, the Pink Toolbox will provide some sort of “Resource Manag- 
er” for instantiating and flattening these persistent objects. This is analogous to 
the way MacApp (along with the Resource Manager) provides for instantiating 
and flattening view resources today. Often a set of related resources must be 


48. User interface in a broad sense—essentially all of the flattened object equivalents 
to the “classic” resources in the Blue world. 
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instantiated together. Constructor can bundle together such resources into a 
Resource Group. 


Resource Component Properties 


Resource components have many of the same properties as code components 
(some with slightly different interpretations), plus several additional property 


types: . 
Generic Properties 


Clients Components that explicitly reference this object. 


‘Components that are explicitly.ré! sd by this ob- 


Resource group c¢ 


Additional Properties 


Actions 


Responses 


Targets Targets of messages sent by this object. 


Connections The list of connections (message paths) originating 
from a connectable component object. 


Superview Superview, if any, of a view-derived component. 
Subviews List of subviews, if any, of a view-derived component. 
Exactly how these properties are managed and manipulated will not be dis- 
cussed in the ERS. However, the above information is presented to further 


elaborate hoops’ underlying component model and how it is used by 
Constructor. 


h@ps March 15, 1990 3.5-63 


Presentation of Constructor manages two different types of collections of resource data: 


Resource Resource Groups, a collection of related resources typically found in applications 
_ and libraries, and Parts Bins, a library-like mechanism for organized storage 
Elements and retrieval of reusable resource components. 


Parts 


Basically, a part is just another name for a Pink resource, both basic building - 
block resources (e.g. icons, text messages, controls, scrollers, windows, menu 
items), as well as resource assemblies designed and saved by the user (e.g. OK 
button, standard Edit menu, Save Changes alert). We find it convenient to use 
the the term part when referring to the resources found in a Parts Bin, so as to 
distinguish them from the resources stored in an application under construc-. 
tion may be identical). 


arts Bins provide the user with a conveni 


or organizing, storing 
ing parts. A Parts Bin is essen 


nent that contains parts. 
in.is. discussed at 


press od Utility Window 
& : [] Plain Dialog 
es 


Figure 20. A Parts Bin browser and a drawer’s contents. 


é Registered /Restricted haps March 15, 1990 35-64 


hoops will ship with a Standard Parts Bin containing a useful set of Menus, 
Windows, Dialogs, Alerts, Controls, etc., so our users won't have to create their 
user interfaces from scratch. This standard Parts Bin will also aid in maintain- 
ing consistent user interface elements between applications (e.g. a consistent 
look for common dialogs such as "Page Setup", or whatever common dialogs 
are appropriate to Pink). 


Resource Groups : 


Constructor also manages Resource Groups—collections of related resource 

components that are instantiated or revitalized as a group. Some applications 

will contain only a single Resource Group, while other applications will find it 
enient.or. necessary to divide their resources across several. Resource 
‘orrespond to different docum ifferent phases 
printing vs. editing), or any:« 


Figure 21. A resource group browser. The upper pane displays a view of 
all the resources in a group. The lower pane is where editing of those re- 
sources is accomplished. 


Constructor provides a default Resource Group Browser (Figure 21) consisting 
of a navigational view (the upper pane) and an editing view (the lower pane). 
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The navigational view contains an iconic representation of all the highest level 
objects in the Resource Group (referring to menus, menu bars and windows— 


' as opposed to the individual menu items and controls they will contain). The 


editing view contains the objects currently being inspected or manipulated. 
Which objects actually appear in the editing view at any given moment is de- 
termined by the item(s) selected in the navigational view. In the editing view, 
objects or collections of objects will appear and, as far as possible, function just 
as they will in the running application. 


The application stationery included with hoops will contain one or more 
Resource Groups which can be used as a starting point for a new application's 
user interface. 


dard viewers for dealin, if Bins: a 


“y 


4 


A Drawer viewer disp! 
Drawer viewers are u 
Bin. When adding a né 
struction, a Drawer vie 


the user interface components in a particular Resource Group. Most layout 
and editing operations take place within the confines of a Canvas viewer. To 
add new items, the user can drag the desired part from a Drawer viewer onto a 
Canvas viewer, or into another object visible in the Canvas viewer. As many of 
the editing and manipulation operations as possible will be available through 
direct manipulation (including size, location, font characteristics, titles, colors, 
menu item arrangement, etc.). Those operations not well suited to a direct ma- 
nipulation interface will be available through some sort of object editor/in- 
spector window, as is done in ViewEdit. Connections between objects 
(described later) are also made within a Canvas viewer. 
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Constructor is Always Available 


Resource-related browsers are opened in the same way that any other hoops 
browser is opened. In addition, class components can be converted into Parts 
Bin parts with one of the selection-specific commands from the source viewers. 
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Cabinet Viewer 


Purpose 


Input 


Output 


Selection Techniques™: 


Operations 
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The Constructor Human Interface 


In this section we show what a number of hoops viewers specific to Constructor 
might look like, and how they might operate. This set is intended to be repre- 
sentative rather than exhaustive. 


A Cabinet viewer displays the drawers contained in a Parts Bin. 


LE a 
ee, aE 


ited. +ti g one of the 
pulls opens the drawer (sending it as an output). Selecting the body of 
a drawer allows the drawer to be repositioned within the cabinet. 


Clicking a drawer pull, opens the drawer if closed or closes the drawer if al- 
ready open. 

An empty, untitled drawer is always present at the bottom (or right) of the 
Cabinet viewer. Renaming this drawer creates a new Untitled drawer. 
Drawers can be deleted with the Clear or Cut commands or with an as yet un- 
determined gesture. 


Drawers are renamed by selecting their title and editing as in the Finder. 
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Drawers can be rearranged by dragging a drawer to a new location within the 
Cabinet viewer. 


Drawers can be moved or copied between Parts Bins via Cut, Copy, and Paste, 
or via direct manipulation by dragging a drawer from one Cabinet viewer to 
another. 


Dropping a part (resource component) onto a Drawer adds the part to this cat- 
egory (and if necessary copies it into the Parts Bin). 


~ 


. Resizing a Cabinet viewer forces the drawer positions to be reallocated to fit 
the new view size. . 
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Drawer Viewer 


Purpose 


Input 
Output 


Selection Techniques 


Operations 
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A Drawer viewer displays the parts contained in a Parts Bin Drawer. Parts 
corresponding to both atomic components and collection components are 


- shown. Individual components within a collection are not shown; instead, col- 


lection components can be manipulated as a whole. These parts are repre- 
sented by small icons which are specified by the user. 


[| NoGrow Window 
[| Grow Window 


Dialog Box 


sescore 


SS ae ac 


arts (resource components). 


Parts are selected by clicking their icons. Clicking the title of a part allows the 
title to be edited. 


Parts can be moved or copied between drawers by dragging or via Cut, Copy 
and Paste. Similarly, parts can be copied between Parts Bins. Parts are added 
to a Resource Group by dragging the part onto the appropriate Group or 
Canvas viewer. Parts are renamed by selecting their titles and editing as in the 
Finder. 


Class components can be converted into Parts Bin parts via a special menu 
command within a source code viewer. Comments or other descriptive infor- 
mation can also be associated with any of the parts in a Parts Bin, and can be 
viewed in a Description Viewer. 
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Gro up Viewer A Group viewer displays the resource components contained in a Resource 
Group. Both atomic components and collection components are shown. 
Individual components within a collection are not shown; instead, collection 
components can are manipulated as a whole. Resource components are repre- 
sented by small icons (copied from a Parts Bin along with the object). 


i——_} 
a Application Cc] Window CI AboutBox AppleMenu’ 
EditMenu FileMenu  (Gruecat)MenuBar  ——i—ts—‘“—s—s*SS : 


ig'atefete'e‘a'e‘elntn'e's''e'e'a's'a'e‘e'ela'v'e'etele's'e'e"eTara'ate'ete'e'etatatacateca'atatate'ela'e'etelatelelelealelele ee eleleeleesaels ss sees eee ee eee eserves 


Purpose J" resource components 2d within a Resource 
woup. Bach partis represented by a smal 

Input A Resource Group. 

Output 

Selection Tech 

Operations 


‘ornments or other descriptive information can: associated with any of the 
resources in a Resource Group, and can be viewed in a Description Viewer. 
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Canvas Viewer A Canvas viewer displays a life-size (potentially scalable) view of one or more 
of the user interface components in a particular Resource Group. Most layout 
' and editing operations take place within the confines of a Canvas viewer. 
Non-user interface components (non-view, like strings or icons) are displayed 
in iconic form. . 


Window 


‘interface 


Purpose Displays a life-size vik 
within a Resource Grc 
Input 
Output 
Selection Technique é 
t brings up an inspector for that 0 
lected it can be moved, resized, or edited, as appropriate. 
Operations View Hierarchy Manipulation 
Modify View Layout 
View Editing/Inspecting 
Menu Layout/Editing 
Connection Editing 


Resource components can be added to a Resource Group by dragging a part 
from the appropriate Parts Bin Drawer view into a Canvas viewer. 
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A User Scenari 
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Resource components can be saved as parts in a Parts Bin by dragging them to 
the appropriate Parts Bin Browser views. 


Tool/Icon Palette Functions 


There are several different operations that can be performed within the Canvas 
viewer. including Edit, Constrain, Connect, Inspect and Test. There are also 
several layers (constraints and connections) that can be revealed. Switching 


. between these operations will most likely be done through an icon bar associ- 


ated with the Canvas viewer. 


3 to Fahrenheit Converte 


Astructor which demon- 
ised in building a simple 
what dated with respect to 
Constructor. If you're inter- 
member of the hoops team for a 


types contains a mock 
tes How:rrin sh:of Constructor’s functie 
temperature conversion application. 
our latest ideas, it conveys much 0 
sted in nSeene this mockup, pleas 
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Extensibility 


Canvas View 
Editing & 
Inspecting 
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Constructor Details 


"Much of this section is currently incomplete or unspecified. Many of 


Constructor's capabilities are based on, as yet, unspecified features of the Pink 
Toolbox. 


An essential aspect of Constructor is its ability to cope with new resource and 
user interface classes—classes created by the user, or supplied to the user by a 
third party. In order to perform its basic tasks, Constructor relies on the fact 
that each user interface class contains a set of basic editing methods (Draw, 
Grow, Move, Edit) or that this functionality is provided in some sort of 
“shadow class” whose name (i.e. TButton and its evil twin TButtonEditor) can 
be found in a dictionary maintained in the Parts Bin. These methods might be 
oe at a sufficiently low level in the class hierarchy (TView) or asa default 
-class“;:so:that-any:new interface class will automatically inherit the: 
ors (see “Object Editors” below; 


tened objects and the’ 
stored with the compon 


abricated Parts 


tandard Parts Bin full of ré: 
} windows, alerts, etc. The exact c 
this standard Parts Bin is yet to be determined. 


hoops and Pink will also ship with various application templates or stationery. 
We envision that this stationery will include a standard set of resources and 
Resource Groups. Although the exact contents and organization of these re- 
sources is yet to be determined, we expect it to include at least the Application, 
some sort of document window, an about box, a menu bar, and several stan- 
dard menus. 


Constructor also provides editing capabilities for resource components. For 
general resource components this will involve a series of resource type specific 
editors (strings, icons, fonts, etc.). For user interface components this will in- 
clude setting font and color characteristics, adornments (a 14 MacApp), win- 
dow positioning, view resizing (with respect to its superview), etc. The poten- 
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tial complexity of this area becomes clear if one imagines combining the re- 
source editors from ResEdit with the view editors from ViewEdit. 


Editing General Resources 


Constructor is able to edit essentially any type of resource that might be pro- 
duced by the Pink system and applications. For common resource types 
(strings, icons, bitmaps, etc.) Constructor will contain a specific editor for each 
resource type. Unfamiliar resource types may either be edited in some generic 
raw (hex?) format or may be displayed read-only. 


P 
such as setting the font or color charag¢te 
way without resorting to special diz é 
fan: user interface item, the use ts the item and chooses the ap- 


An additional advantage is 


to modify all o 
accessible throug 


e ancestry of the object often leads to common y modified attributes being 
scattered about the dialog. 


Asa solution to this problem, Constructor allows the editing dialog to have 
two forms, essentially a short and long form. In the long form the user is pre- 
sented with total control over the object, whereas in the short form only the 
most commonly used (determined by decree) editing controls are available 
(Figure 26). 


Object Editors 


One, as yet unresolved, question is whether the actual code for an object editor 
lives in the object itself, or in a separate “shadow class”. We currently believe 
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that objects will have to have some sort of “being-edited” state so they can re- 
spond differently to mouse-clicks, etc., when being edited. An example of 

' these behaviors is that normally when the user clicks the title of a check box, it 
toggles the state of the box just as if the click had occurred in the box. In 
“editing-mode” however, we would like to have a click on the title of the check 
box mean that the title should be edited. This specialized knowledge about the 
internal structure of an item would seem to favor having the editing code de- 
fined asa part of the class itself. There are other issues to consider in deciding 
where this code should reside. If a “shadow-class” is used, Constructor must 
manage the extra baggage when copying parts from one Parts Bin to another. 
However, if the editing code lives in the class, then the author must provide the 
editing capability—it cannot be added or modified by the user. 


interplanetary Convertor 


(_] Draggabié 
[_] Resizable 


Reset Window 


Figure 26. An example of an editing dialog for the window object dis- 
played in the canvas viewer. 
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View Layout Details 


Constructor will allow view location and size to be directly manipulated. In 
addition, the view hierarchy will be easily modified and traversed. The details 
of this are yet to be determined. 


Constraint-Based View Resizing Details 
_The Pink Toolbox provides a powerful, but as yet undetermined, constraint- 
based view resizing mechanism. Constructor must provide a convenient user 
interface for specifying these constraints. The current Constructor mockups 
are based on springs, which allow for resizing, and fixed-size turnbuckles.” 
traints.are.attached between the edges of a view objec and the cor- 


—_—s by 

¢ n | immediately when 

tor will also provide tools for 
ng resizing based on screen 


enever pos- 


Connection Editing Details 


To allow simple messages to be sent between objects, the Pink Toolbox pro- 
vides Responders (objects capable of performing an action in response to a 
message) and Stimulators (objects that send a message to a Responder as the 
result of some internal state change—possibly triggered by the user). 
Constructor allows the user to make connections between such objects and to 
specify both the message trigger and its content. An example of making a con- 


49. Similar to the model presented in Building User Interfaces by Direct Manipulation, 
Cardelli, L., Proc. ACM SIGGRAPH Symposium on User Interface Software, 
pp152-166, October 17-19, 1988. 
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Connections 
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nection can be seen in Color Figure 2 at the end of this document. This figure 
shows the connection inspector window, which is used to view or modify con- 


- nections. 


This section explains the connections between objects produced by » 
Constructor, as well as the gory details of the underlying source code. At pre- 
sent, most of what follows is unimplemented in Pink. In several discussions 
with David Goldsmith and Frank Leahy we have agreed on this general archi- 
tecture as satisfying the needs of both Pink and Constructor. 


Responders 


In the current Pink architecture, objects that can respond to messages (text or 
tok 4 al method calls) are created with. 


‘ fonal messages to 
< architecture these 


Responders are only half the picture though. For Constructor, we need an 
equally flexible way to have objects send messages to arbitrary targets in re- 
sponse to some internal state change. For instance when an OK Button is 
clicked it should be able to send a message. In MacApp this message is sent up 
the view hierarchy, via the method DoChoice(), to the document and finally to 
the application. Somewhere along the way someone will take an appropriate 
action. While sufficient for many situations, this architecture does not support 
the communication necessary for the style of user interface programming 
Constructor needs to support (e.g. dependency graphs). Code must be written 
to implement the message network. 


What we need is the following: each user interface component has a predeter- 
mined set of conditions under which it may send a message to another object. 
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Examples of these conditions include: being clicked, on a keystroke, while the 
mouse is over, and various types of state changes (e.g. from empty to contain- 
ing text, or dimmed to highlighted). Let’s call all objects with this capability 
Stimulators, since objects other than user interface components may want this 
capability as well. 


OutputPorts 


In the definition of a Stimulator, there will be a list or array of OutputPorts, one 
for each of the conditions under which the object will want to send a message. 
An OutputPort contains a pointer to the target for the message, if any, which 
must be derived from MResponder, and a pointer-to-member-function which 

i thod in the target object that should handle the mes- 


tPort might look like: 


esponder: : *ActionPME Stimulusé msg); 


class TOutputPort : public ... { 
MResponder* fTarget; 
ctionPMF fAction; // PtrToMember decl 


st TStimulusé& m 


Here’s what 
the mouse is 


eStuff() { 
(StillDown()) { Be 
TBooleanStimulus msg(Mou 
f£StillDownOutput.Send (msg) ; 
} 
if (ReléasedOverButton()) { 
TStimulus msg; 
fClickedOutput.Send (msg) ; 


}3 


Pointer-to-members are used, instead of the usual token-based messages for in- 
creased performance.? 


50. This pointer-to-member based implementation is not required. Token-based 
messages could be used if performance is not an issue. 
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. Connecting Objects with Constructor 


When the user draws a connection between two objects (described in the 
Canvas Viewer Human Interface section above), Constructor will have to check 
that the message sender is in fact a Stimulator and that the target object is a 
Responder. In addition to message source and destination, the connections, or 
rather the messages sent via the connection, have an associated type. Using the 
message type, Constructor can make certain that OutputPorts which send a 
message of type TTextStimulus (or a subclass) are only ever connected to mes- 
sage handlers that expect to receive messages of type TTextStimulus (or a su- 
perclass). The names and types of the sender’s TOutputPorts and the names 
and types of the target’s message handlers will be maintained by hoops since 
these are ahaa of connectable components. Constructor can enforce this 
nnections by disabling incompatible:¢t s 
indow in Color Figure 2 a 


‘the user completes a tonnection, Construct 


‘ $ in the appropriate 
hutputPort in the sender side of the connectid: 


yr instan vi io jia- 


log items. This set 
peaters, etc. 
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hoops is a Pink 
Application 


Particularly 
Important _ 
Dependence 
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Dependencies on Pink 


It is important to remember that hoops will be one of the first, and possibly for 
quite a long time, one of the largest Pink applications. This means that hoops is 
critically dependent on parts of Pink being ready and available, and capable of 
handling certain loads.5! The development environment we want would take 
much longer and require much greater manpower to accomplish, if the entire 
program was being implemented from scratch. Fortunately this is far from the 
case because hoops is being implemented on and in Pink.°? 


People associated with Pink have always been flexible and willing to help. In 
fact we would like to think that all of Pink is engaged in the crea f hoops. 


eavy use of standard Pink ca- 
hoops to have essentially the 


Versions 


We expect to use the versioning facilities supplied by Pink. The Program man- 
agement chapter of this document describes the sort of capability we think we 


51. To provide the right degree of contrast, try to imagine MPW editing built on top 
of Blue TextEdit. 

52. hoops will be used to implement hoops from the earliest possible opportunity. 

53. Pinkos, don’t take this as a promise that hoops won't cause you to change both 
your working habits, and your designs. This will most certainly happen, but 
always bearing in mind our common goal of producing a working environment 
that we ourselves, as designers, artists, authors, and programmers would want. 
We apologize if this sounds like hype. Ideals need to be lofty so that they do not 
chop the heads off results. 
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need, but we are flexible in this area and believe that a powerful, standard 
scheme is important. 


Collaboration 


hoops will follow the Pink model of collaboration and we expect most of the 
hard design and implementation work will be done by Pink.+ There is a 
limited description of what we think we need in the Program management 
chapter. A very important thing (remembering that “us means you”), is to be 
able to take our work home. 


Undo 


software folks get. 


ps needs it. We would rather use the stan odel even if we have 


te our own implementation of func 


tends to use 


e are particularly dependent here since our user interface is being designed 
alongside the rest of Pink’s. hoops is a very early Pink application but we still 
want it to exemplify the Pink human interface. 


Finder and File system 


Like every other Pink application, hoops will be dependent on the Finder and 
the File system. However hoops requires special services with regard to 
launching applications, among other things. 


54. Thanks Arn, Larry, Jack, and Mrs. Calabash (wherever you are). 
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Dynamic libraries 
These are crucial. The design and extensibility of hoops depends on them. 


OS and Network 


In order to debug programs in the most powerful and straightforward way, 
hoops will need certain run-time and network facilities. 


Resource Manager 


: hoops relies on the Pink Toolbox’s ability to save and restore flattened objects 
a This also includes the eee to flatten: pointers to 


Constrain 


Currently, hoo ing : onstraints 


Sop cto eee el i i ee ee 
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Dependencies on CompTech 


Who Said The observant reader will have noticed that this document assumes the exis- 
: tence of at least one compiler. The observant and astute reader will have no- 
Any thing About ticed that this compiler is being asked to do some mildly unusual things. 
Compilers? 
It almost goes without saying that hoops needs the compiler(s) developed by _ 
the Compiler Technology team. In order to provide the incremental system 
envisaged, it is necessary for the compilers and the rest of the environment to 
communicate much more fully than has been usual in the past. Language sen- 
sitivity in the editor for example, will rely on information created by the com- 
piler. Conversely the compiler will rely on symbol and dependency informa- 
tio ‘vironment. 


tive and en- 
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Glossary _ 


ATOMIC COMPONENT a component that is not further subdivided into smaller components. 
BROWSER a loosely used term to describe a window which has two or more panes. 


BROWSER CONSTRUCTION —_—_an archaic term used to describe the technique for creating views that interact 


KIT with each other, or “connect” to each other. 
C++ a really swell programming language. 
CABINET VIEWER 


taining the resources in the parts bin. 


CANVAS VIEWER 1¢ Or more of the 


r that displays a life-size 
5 ina particular resource 


CLASS COMPONEN 
CODE COMPONE Q ritten ina 


COLLABORATION 


COLLECTION COMPONENT 


ymment block, and descriptio 


COMPONENT a named object that represents a semantic element of a program. All data in 
a project is represented as components. Examples of components include 
classes, functions, type definitions, and libraries. See also atomic component, 
code component, collection component, connectable component, 
organizational component, resource component, and user interface 
component. 


CONFIGURATION a set of versions of components that make up the state of a project at a given 
time. 


é Registered /Restricted hops March 15, 1990 3.5-85 


CONNECTABLE COMPONENT a resource component that descends from MResponder and/or MStimulator 
and has the ability to send and/or receive message to/from other 
connectable components. 


CONNECTION a metaphor that represents the trigger and message sent from one 
connectable component to another. 


CONSTRUCTOR that part of hoops used to create the resources of a program, most 
importantly, the user interface of a Pink program. See also canvas viewer, 
cabinet viewer, drawer viewer, resource group, parts bin, and resources. 


CUSTOMIZATION the act of creating new and unique combinations of the existing set of tools in 
hoops. See also extension. 


DAVE AND TOM 


DERIVED PROPERTY 


DESCRIPTION roperty Of a" it i ock describing a 
) mentation system 


DRAWER VIEWER 

DYNAMIC CLASS 

EDITOR 

ENVIRONMENT FRAME! 

EXPORT the act of converting one or more hoops components into a form external 
from a project, such as an operating system file. 

EXTENSION the act of adding new and unique tools to hoops. 

FILE COMPONENT a component that represents a stream of text, as in an MPW text file, though 
it is not saved as an operating system file. 

Group VIEWER a view of the top-level resources in a particular resource group. 
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Hoon human-oriented object programming system. Sometimes incorrectly referred 
to as the heretical object-oriented programming system. 


IMPORT the act of converting source code from an external source into one or more | 
hoops components. 

INTRINSIC PROPERTY a property whose value is stored as part of a component. 

MACRO mutants to be avoided at all costs. 

MARGINAL COMMENT _acomment placed in the margin area of source code. , 

MESSAGE a Pink message (TStimulus) that contains data to be sent between resource 


components in response to a stimulus. 


MODULE 

NAVIGATION 

ORGANIZATIONAL 

COMPONENT 

OUTPUT PoRT 

PANE 

PART 

PARTS BIN 
Constructor. | 

PRIVATE Co lock embedded in the im 

PROJECT the source code, object code, documentation and related data of a software 
development effort, represented as a wholly independent entity to hoops. 

PROPERTY a characteristic or attribute of a component. Components can have any 
number of properties, depending on the component's type. Examples of 
properties are source code, object code, interface, or description. See also 
derived property and intrinsic property. 

PROTOCOL the set of member functions of a class that defines how other parts of a 


program communicate with a class and its subclasses. By having a protocol, 
it is possible to add new subclasses without changing the other parts of the 
program, because the subclasses respect the protocol. 
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RESOURCE a flattened object stored in a fork of an application. 


RESOURCECOMPONENT _._ the hoops representation of a resource. 
RESOURCE GROUP a collection of related resources that are instantiated or revitalized asa 
group. 


SELECTION-SPECIFIC MENUS A set of commands or operations that apply specifically to a given selection 
in a view. One example of a selection-specific menu is the pop-up menu 
used in the current hoops mock-up. < 

STIMULATOR a connectable component that sends a message in response to a state change 
(i.e. a character was typed, the button was clicked, etc.). See also output port. 


STYLE SHEET a technique for associating a visual style with the syntactic elements of 


TOM AND DAVE egos?) the size of planets 

TOOL Be fming some action, o some data in 
wops. hoops is implemented as a set of tool: this definition 
eviates from, and is much broader than thé nition of a tool. 

TRANSFORMER yes the value of a proper: 

TRANSLATOR roperty of ad 

USERINTERFACE = = ~— a connectableé're escends 

COMPONENT user interface of a'P am. Th 

dialogs, alerts, and ie® 
VERSION nt. 


VIEW CONSTRAINTS : 


ViEWEDIT eating MacApp view resources \pp program. 


VIEWER a tool that displays a property of a component. 


a a 
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TRowDataSet 


TRowDataSet 
class TRowDataSet: public TDataSet 


{ 
private: 
RowNumber fRow: 


public: 
TRowDataSet(TTuffyDacument* itsDoc, RowNumber row); 
virtual ~TRowDataSet(); 


{row = fRow) { 
item = At(row); 
if (col -> tsEqual (item)) 
retum (item); 


-| 
retum (NIL); 


Color Figure L Source code browser. This browser consists of two connected views: an 
interface view and an implementation view. Comments are shown with a gray background. 
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Online Tech 


1 Documentation for Pink . 
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General plan 


The Developer Technical Publications group, reporting to Trish Eastman, and Scott Knaster, 
reporting to Doug Brent, are working on creating technical documentation that Pink developers 
will use to write software. A large part of this documentation will exist online and will be 
available to developers in the “heat of battle” — that is, directly from HOOPS, the Pink 
development system. This paper describes the preliminary plan for putting Pink technical | 
information online. 


The complete Pink technical documentation suite is described in another document in this 
binder, but here’s a brief description of the parts. There will be an overview of Pink 
capabilities, designed for people who will 

look something like fandin: 
pictures, a friendly i 


There will be two bee Pink in more depth, one 2 who like to read 
about theory befor ing title is The Pink Fo 
tutorial volume for those who like to learn as they go (How to ¥ Program). We will 


investigate prod 


g, interactive online versions of these book 


The documentati ch online reference to every 
online reference ma@ 


focuses on a specific Pink 8 
book will be the definitive reference 


The online descriptions are the heart of our project. We’ve already started writing them. 
Eventually, they’ll be displayed in HOOPS (and maybe elsewhere, as well). Until HOOPS is 
born, you'll be able to read online descriptions with Mouser, 411, and HyperCard. The 
appearance of online descriptions in HOOPS depends on the design of HOOPS itself, and 
probably the Component Editor in particular (if that’s still a valid name for a place in 
HOOPS). 


Online books are the more interesting (= harder) part of the project. Officially, we’re just 
investigating this part of the project. That’s because we'll have paper versions of the 
documents to fall back on in case we can’t complete a online book in time. Asa minimum, we 
expect to have online a version of each book that’s functionally the same as the paper version. 
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Our idea for online books is this: imagine HyperCard, except that (1) the metaphor is not an 
index card, but a book, and (2) it’s done in the Pink application engine, so it has CHER and 
everything else that’s Pink. We think that using a book metaphor is a good idea. Everybody 
knows how to use books in a linear fashion, and many people know how to use tables of contents 
and indices ~ sort of a “manual hypertext”. A book provides a comfortable, linear frame of 
reference for users, which they can use sometimes (by reading linearly) and abandon other times 
(by following links). 


Our online books will look like books on the screen, complete with (optional) page numbers. But 
they’ll be magical books, because they'll include hyperlinks, sound, animation, content ' 
browsing, fold-out pictures, annotation, and other Pink goodies. Of course, online books can be 
also be used ina completely linear fashion, and can even be turned into paper books 
automatically by removing the multimedia and hypertext features. In fact, existing OCR 
technology could provide developers with the ability to automatically create online books out 
of paper books (although without any hyperext or multimedia additions, of course). The 
developer could then rate the 


We believe that the 
and presents a com 
for online books wil 


ements investigation of existing eo 
looked at, or to make suggestions for 


We'll also use HyperCard 2.0 to create prototype online books. Depending on the progress and 
direction of Jane, we may be able to use Jane as a base for prototypes at some point. We don’t 
know who will actually create and maintain these prototypes yet. 


Of course, we'll test the prototypes on real people (probably PUG members as well as Pink 
people) and we'll check the readings on the electrodes we'll attach to their heads. 
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Don Quixote 
The Pink UNIx Adapter 


Geoff Peck 


Don Quixote and Sancho Panza 
drawing by Pablo Picasso, 1955 
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Introduction 


Don Quixote, the UNIX adapter for Pink, allows end users to run standard UNIX software ona 
Pink Macintosh while simultaneously running Pink and Blue applications. .End users will be 
able to exchange information between the three “worlds” in several ways — at the minimum, 
cut and paste and limited inter-system file access will be implemented. Since UNIX is a 
essentially a text-based system, Don Quixote will allow reading and writing of unformatted 
Pink text files from the UNIX environment. UNIX programs will be able to access Pink files, 
and a UNIX developer might choose to write code which can decode one or more non-text Pink- 
file formats. Don Quixote will not perform such translations automatically. Blue text files 
will also be accessible to UNIX applications through a similar mechanism. 


Developing Don Quixote also will help ensure that Pink contains the required facilities for 
third-party developers | . It also will serve as a substantial desi 
and programming ex can be distributed to third- “party.€ 


Detailed plans for D 
section is prelimina 
are currently bei 
section at the end 


: process; the informati 
“oncentrates on one 
tives are briefly de: 


ternatives which 
he alternatives 


524 ’ 
this chapter. 


Don Quixote will include a minimal se 
to make the ‘system operate in a manner ¢ 


Don Quix 
rather, it i 


capabilities ‘the difficulties associated 1 


otrategy 


The strategy for Don Quixote is quite different from the path being taken by the “traditional” 
UNIX workstation vendors (SUN, HP, DEC, etc.), by our own A/UX group, or by NexT. These 
companies are taking a complex system and putting “pretty wrappers” on top of it to make it 
nicer looking and easier to use. Both NeXT and A/UX are using this approach to attempt to turn 
a relatively traditional UNIX workstation into a personal computer. The “wrapper” approach 
does not address the fundamental problem — the complexity of UNIX. 


Don Quixote is an entirely new environment, built on top of Opus/2, which provides the 
facilities of UNIX without the complexity. This is done by building a new system which 
conforms to relevant standard interfaces, but does not have the complex internal and 
administrative structure of UNIX. The benefit to the user is that Don Quixote will have many 
fewer “moving parts” than a traditional UNIX. 
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Don Quixote is an integral part of the Pink software release. It should be packaged at no 
additional charge with every Pink system. By virtue of the number of installed machines in 
the high-end Macintosh market (68020 processor or greater), the introduction of Pink with Don 
Quixote will immediately change the installed-base balance in the UNIX marketplace. 
Current UNIX software vendors will be strongly encouraged to ensure that their programs work 
under Don Quixote, simply due to the sheer number of Macintoshes which run Don Quixote. Don 
Quixote must provide a high degree of compatibility with industry standards in order to reduce 
the investment and time required by UNIX program developers. Availability of many UNIX 
packages in addition to the well-established base of Macintosh applications will immediately 
establish the Macintosh as the system of choice for many customers who require UNIX-based | 
solutions. 


Don Quixote, like the rest of standard Macintosh system software, is solely Apple-developed 
code. In certain cases, we may elect to include with Don Quixote some code which is available 
to the public, such as GNU software from the Free Software Foundation. If Don Quixote were to 
be built using existin 1p would have to pay a yay to ATS 

copy which was ship ; 

be due, and it will 
base at low cost. 


Source code for D 


example of how. 
operating syste 


AT&T UNIX license — and we ca 5, 
available to others by such advanced tis 
Apple licensing restrictions as well. 


administratis i 
program co x ion bi i i ided Don 
Quixote a xX 

and/or 88000 oh of 

which relies ¢ a not sera: by Don Quixote I ipilation, 
and possibly source code c anges, in order to run under Don Quixote. Since Don Quixote supports 
execution of most standard UNIX programs, however, this development will be able to be done 
using standard UNIX tools. This eliminates the need for UNIX developers to learn a new 
development environment, which has been identified as a major stumbling block to moving 
UNIX software to the Macintosh. 


Standard UNIX utilities or their equivalent will be available for use with Don Quixote, 
packaged as several functional groups. A minimal set of utilities will be included with the 
basic distribution included with Pink. Others will be available separately through standard 
Apple system software distribution channels — from public distribution sources, or for a nominal 
charge from Apple and/or dealers. This type of packaging permits a typical office- 
environment Pink system to run much UNIX software with relatively little disk overhead or 
added complexity. Users who require additional UNIX facilities would load them when 
required, and would use more disk space. 
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Tactics 


Producing a UNIX work-alike while simplifying the system is a challenging but achievable 
task. The first stage is identifying the appropriate standard or combination of standards with 
which to guide the effort — the federal information processing standard FIPS 141, IEEE’s 
POSIX standard, AT&T’s System V release 4, OSF/1, and/or X\OPEN. The standards each 
include system call interfaces, library interfaces, and a standard program suite. Many of the 
standards include optional features, which will be evaluated to see how useful they will be vs. 
how much complexity they add. . 


The result of the standards effort will be a single document which specifies the interfaces and 
programs which Don Quixote will support, and provides an initial cut at how the system will 
be split up into packages. After the standards document has been finalized, several 
implementation specificat oped. One implementation specification wi 
describe how the ada a 


ed by Don Quixote is 


Don Quixote is one of two adapters: 
developers may choose to implement 'a¢ 
framework will allow implementation 


Currently, two possible adapter architect 
Opus /2’s exce tion- handling facility is us 
exceptions : 
code takes a 
| architecture is shown ts 
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Don Quixote interface code 
and local static data 


Don Quixote 
server teams 


e terminal emulation 
¢ file system interfaces 
* process creation, etc. 


UNIX processes 


It is possible that this arrangement may 
processes work,.in particular with Syste 
tory. An alternative 
rtion of the ad: 
un as standard Opus teg 
allows the ada irtual environment for on 
managing them in'a'manner different from that of Opus teams. 
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Standard 
Pink Services 


UNIX Adapter 
Service Processes 


UNIX processes 


Currently, it is 4 


gers” around a “real”: 


“Real” UNIX syste umber r of pieces which could be re-des pné more 
automatically and safely. The file system, for example, could be replaced by one 2 which j is 
crash-resilient, thus eliminating file-system checking (fsck) and the resulting delays and 
confusion. The UNIX-to-UNIX transfer facility (uucp) can be re-engineered to keep its 
information in a single database, rather than dozens of small control files which are scattered 
in several places in the file system hierarchy, and a simple administrative interface for this 
single database could be devised. 


UNIX systems typically fail to operate in an expected manner when any one of dozens of small 
control files or programs are slightly incorrect or are out of place. One could envision a system 
which attempts to fix these files automatically, but such a system glued on top of an existing 
UNIX is simply adding a layer of complexity, which may or may not function properly 
depending on the user’s particular environment. 
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A “real” UNIX will always, fundamentally, have quite a few pieces which may need to be 
adjusted by a “wizard”. Evenif the “wrappers” can allow a non-computer-guru user to set upa 
system in a standard manner, configuration changes usually are needed for a given work 
environment which must be performed by a “wizard”. Such changes will frequently cause the 
“wrappers” to no longer work. 


Why should Apple have two UNIX products, A/UX and Don Quixote? 


Don Quixote and A/UX address two separate markets. Don Quixote provides UNIX capability 
for the user who occasionally wishes to run one or more UNIX programs on his or her Macintosh. 
A/UX provides full UNIX capability for the user who requires it, as well as the capability to 
run occasional Macintosh programs. Neither product meets the needs of the users of the other 
product. 


Apple's software distribution for the Macintosh works well because little or no channel suport 


is required. How can this.8 ply. for..a.complex..LINIX-like system? 


Don Quixote will be 
need to ask “do Iw 
the installation disk 
Configuration an 
will be required fo: 
Quixote will allos 
UNIX systems, 
(or from) the s 


ser pops in 
ler program. 


What docume 
documentatio 


a la Inside 
volume se 
use. 


s which was exception 


Will Don Quixote compete with Pink for users? For et le What -will be the impact on 
users? 


UNIX applications and Macintosh applications are currently typically complementary, rather 
than competitive. Don Quixote will allow that symbiosis to continue, on a single machine. For 
users, then Don Quixote expands the computing opportunities, rather than forcing them to make 
a choice between Don Quixote and Pink. 


It is possible that some developers will prefer to develop software for Apple’s machines in the 
Don Quixote environment rather than the Pink environment. The availability of a UNIX-style 
development environment (both tools and programming environment) is likely to make the 
perceived cost of entry to application development on a Macintosh much lower. Don Quixote 
therefore may encourage many applications to be written for Pink-based Apple products that 
otherwise would not be written. 
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Alternatives 
Here are several of the alternative implementation architectures which were considered: 


Direct execution solutions 


1) An Apple-developed adapter which can directly execute UNIX binaries which comply 
with the System V Release 4 applications binary interface (ABI). 


2) An Apple-developed adapter which can directly execute UNIX binaries which are 
compiled specifically for this adapter. 


Library-based solutions 


3) An Apple-developed library which allows most UNIX source programs to be compiled and 
linked to execute in the Pink environment. 


4) An Apple-developed:library which allews'sdine UNIX source programs to be 
linked to execute. 


Where does the cod 
5) Portan existing 


UX) to run on top of Op 
existing AT&T UNIX libraries to interface to: : 
The Pink-do-nothing strategy 

7) Provide a Pink adapter.for,A/UX, and don’t provide a 


years of effort. However, eonenions 
requirements. I would estimate any of th 
man-years, with less than 10% differenc 


such products to 1 : 3 
find it extremely difficult to attract UNIX software vendors and sometimes-UNIX-users to 
Pink. There are a number of products which tried the library-based approach, the most notable 
of which were Apollo Computer’s early UNIX offerings and the various adapters which 
allowed UNIX programs to run under DEC’s VMS. None of these met with market success. 
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dhe alternatives involving AT&T code may require somewhat less development time than the 
fully Apple-developed alternatives; I would estimate this savings at no more than 30% of the 
development cost. These alternatives would require Apple to purchase an AT&T UNIX license 
for each system we ship with Don Quixote, or would require us to package Don Quixote as a 
separately licensed product. I believe that it is very important for us to offer Don Quixote to our 
customers on the same basis as we do other Macintosh system software — “bundled,” at no 
additional cost to the user. Thus, Apple would have to pay AT&T for a UNIX license for each 
and every Macintosh which exists and is capable of running Don Quixote at the time of product 
introduction, as well as to pay AT&T a royalty for each system produced after that point. This 
would be a multi-million dollar expense. (Currently, $50 per system is the least expensive _ 
UNIX license; even if it could be negotiated down to $20 per system, the up-front payment to 
AT&T would be in excess of $20 million!) 


The several library-based alternatives (3, 4, and 7) suffer from several specific technical 
problems: 


atic 


1) UNIX programs « 
relevant to the 


space contain only inform 


wd that any system informa : pertains to 


2) 


3) 


are tied to foreign instruction sets i ible. ry 
rather than a UNIX adapter will not: 
produce an adapter. 


In light o 
technical 


apter are (1) and (2) above 
full UNIX proces nft-within the Pink framework. 
Then, the remaining question is whether to use the System V Release 4 ABI standard or to go 
with a standard of our own (Pink-only UNIX binaries, or A/UX binaries, for example). 


Appendix A - System Call List 


Following is a consolidated list of system calls obtained from the POSIX Standard (Portable 
Operating System Interface for Computer Environments, IEEE 1003.1) and the current 4.3BSD 
Berkeley UNIX system running on AppleVAX. This list needs to be reconciled with other 
relevant standards, particularly AT&T’s System V Release 4. A similar list needs to be 
generated for library routines. 
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The third column indicates the relevant section number in the POSIX specification or, in the 
case of Berkeley-only system calls, “B/” followed by an indication of the class of system call. 
The fourth column contains working notes on the system call’s origin and whether or not the call 
should be implemented in Don Quixote: 


P = privileged call, not implemented in Don Quixote 

C = in 4BSD compatibility library, implemented in Don Quixote 

+ = added to POSIX; not in 4BSD, implemented in Don Quixote 

? = not in POSIX, in 4BSD, may be implemented in Don Quixote 

x = not in Don Quixote ‘ 


3. Process Primitives 


fork create a new process 3.131 
execve execute a file (also 5 other variants) ic ee beer 
wait wait for process termination 3.201 
waitpid i j 3 

_exit 

exit aoe 
kill Pe 
sigsetops 11, add, del, isme: 6343 
sigaction  =38kanmine and: change ssc Al action 3.4 
sigprocmask sxamine and change blocked signals 13D 
sigpending xamine pending signals -3.6 
sigsuspend ait for a signal Par 
alarm ignal after specified ti 74.1. -C 
pause SSS execution 24.2 + 
sleep 4.3 C 


3a. 4BSD P 
brk 


killpg aS Ss group 4 
profil x 
ptrace process tra¢é 
sigblock block signals 
sigpause atomically rele d signa 

interrupt 
sigreturn return from signal»: 
sigsetmask set current signal : 
sigstack set and/or get sign tack conte 
sigvec oftware signal f ‘ies 
vfork “awn new proces virtual memot 
4. Proc mt 
getpid Sification Aad 
getegid group id Geel 
geteuid get effec ive user id 4.2.1 
getgid get real group identity 4.2.1 
getuid get real user identity 4.2.1 
setgid set group id 4.2.2 
setuid set user id 4.2.2 
getgroups get supplementary group access list 4.2.3 
cuserid get user name 4.2,48- + 
getlogin get user name 4.2.4 
getpgrp get process group identification 4.3.1 
setsid create session and set process group id 4.3.2 
setpgid set process group id for job control 4.3.3 + 
getppid get parent process id 4.4.1 + 
uname system name 4.4.1 
time get system time 4.5.1 Cc 
times get process times 4.5.27 © 
getenv environment access 4.6.1 C 
ctermid generate terminal pathname ie no Ss 3 
sysconft get configurable system variables 4.8.1 + 
4a. 4BSD Process Environment 
getdtablesize get descriptor table size B/Proc 


ras ee ea a et ae Se ag Sg Ne a a ee 
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getpagesize get system page size - B/Proc 


getpriority get/set program scheduling priority B/Proc x 
getrlimit : control maximum system resource consumption B/Proc x 
get rusage get information about resource utilization B/Proc ? 
gettimeofday get/set date and time B/Proc 
setgroups set group access list : B/Proc 
setpgrp set process group B/Proc 
setregid set real and effective group ID B/Proc 
setreuid set real and effective user ID's B/Proc 
syscall indirect system call B/Proc ? 
§. Files and Directories 

closedir close directory for reading Dede. § 
opendir open directory for reading Soave. HC 
readdir read entry from directory Bove Ae 
rewinddir position to read from start of directory 5.1.2 C 
chdir change current working directory Se 2ek 
getcwd get working directory pathname (BSD: getwd) 5.2.2 C 
open . fa 5 edhe: 
creat Ste an existing one eer 
umask sk 340 
link 5.3.4 
mkdir 5.4.1 
mkfifo 36: 5.452. <t 
unlink emove directory entry Prowl 
rmdir emove a directory file 5.5e2 
rename ‘change the name of a file 5.5.3 
stat S.6a2 
fstat Suboe 
access 5.6.3 
chmod 4 
chown =) 
utime a 
fpathconf + 
pathconf get configtk + 


5a. 4BSD Files and Direct 


ioctl control device ? 
chroot change root direct: 2 
readlink read value of a sy 

symlink make symbolic link 

truncate truncate a file to 

6. Input Jutput Primitives 

pipe i 

dup 1 
dup2 Zou 
close 6.3.1 
read “E Er 6.4.1 
write write output 6.4.2 
fentl file control 6.5.2 
lseek move read/write pointer 615.3 
6a. 4BSD Input and Output Primitives 

flock apply or remove an advisory lock on an open file B/IO ? 
fsync synchronize a file's in-core state with that on disk B/IO_ ? 
mknod make a special file B/IO ? 
mount mount or remove file system B/1O . 2 
select synchronous I/O multiplexing B/IO 
sync update super-block B/IO 
6b. 4BSD Network and Interprocess Communication (Sockets) 

accept accept a connection on a socket B/Socket 
bind bind a name to a socket B/Socket 
connect initiate a connection on a socket B/Socket 
getpeername get name of connected peer B/Socket 
get sockname get socket name B/Socket 
getsockopt get and set options on sockets B/Socket 
listen listen for connections on a socket B/Socket 
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receive a message from a socket B/Socket 


recv 

send send a message from a socket B/Socket 
shutdown shut down part of a full-duplex connection B/Socket 
socket create an endpoint for comminication B/Socket 
socketpair create a pair of connected sockets B/Socket 
7. Device and Class~-Specific Functions 

tcgetattr get terminal state Te21 
tcsetattr set terminal state dad2ed 
tedrain wait for terminal output to finish 7.2.2 
tcsendbreak send break 7.2.2 
tcflow suspend terminal input and/or output 7.2.2 
tcflush discard pending terminal input/output deen & 
tcgetpgrp get foreground process group id 7.2.3 
tcsetpgrp set foreground process group id 7.2.4 
Ja. 4BSD Device and Class~-Specific Functions 

vhangup virtually “‘hangup'' the current control terminal B/Dev ? 
XX. 4BSD Administrative Functions 

reboot 

setquota file system 

adjtime * synchronization of the 

swapon ¥terleaved paging/sw 

acct fe Pf 

gethostid get/set unique identifier of current ho 

gethostname get/set name of current host 

getitimer get/set value of interval timer 

quota manipulate disk quotas 
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Pink Documentation Suite Plan 


Apple Developer Technical Publications 


Confident 


é. 


Draft 
© Apple Computer, Inc. 1990 
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Goals 


The goals of the Technical Publications Pink documentation suite are to provide 


" a complete description of all developer-accessible parts of the Pink system 
" multiple entry points and varying treatments of the information corresponding to 
the skill levels and learning styles of all developers 
s navigational assistance so that readers can find the information they need without 
becoming bewildered or wondering how to get started 
The sheer volume of the information that we must provide will require us to use innovative 
technologies, IREEINS online delivery systems and creative ways of presenting access to the 
information. : 


In keeping with documentation needed 
by general purpose application developers. The Networki unications Publications 
department 1e documentation required by ¢ f communication software. 
Customer Ca : on, including setup and 


utility guides 


Engine and the Object Toolbox. The 
families of classes that call the code th 
appucation incorporates classes from 

ises.the families of classes that 


Application Engin Object Toolbox 


Application Text 
Document Graphics 
Event Operating System Utilities 
View Operating System Services 
Command Network Services 

Sound 

Imaging 

Scripting 
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Pink documentation model 


The documentation model strives to meet its goals while also delivering documentation when 
Pink ships. Since there are never enough resources and since Pink is still under development, we 
have designed a model that allows us to begin with the most critical and stable information,, 
ensuring that we provide enough information to allow developers to get started. After the first 
customer shipments, we will continue to add information about less critical and late-developing ~ 
features and to update particular components of the suite individually as required. 


Our model provides 


" i ti gems “What is Pink?” 


“ ies i ifi icati answer the 


In addition, we wi dateri idelines,-a.glossary, 
and an index. = 


The model is rep 
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The Pink Documentation Suite 


Introduction to Pink 


How to Write 


A more complete description of the suite elements follows: 


a The Introduction to Pink advises programmers and programming managers of the 
advantages of object-oriented programming in general and the Pink system in 
particular. 

«The Pink Foundation describes in detail the concepts of the Pink system and the 
interrelationships of the families of classes. This manual, used in conjunction with the 
online reference, is aimed at the type of programmer who likes to learn the concepts 
and understand the model before starting to work. 

« How to Write a Pink Application describes how to write a Pink application using the 
HOOPS development system. This manual is directed toward programmers who like 
to learn by doing. The eventual goal of this product is to be an interactive online tool. 
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However, if the online tool to produce this product is not available at the first 
customer ship of Pink, it will debut as a paper document. 

u The Online Class and Method Reference provides descriptions of all the Pink classes and 
the methods that pertain to them. As our online tools become more powerful, we 
plan to add animations, code samples, and other interactive features to these 
descriptions. For plain vanilla applications, the developer will need only the online 
reference used in conjunction with either the tutorial or the foundation manual. The 
online reference will be developed first using an interim tool to search and display ~ 
the information. 

us The Focus Library consists of a series of definitive descriptions, which correspond to 
elements in the Application Engine and the Object Toolbox. In addition, there will be 
some focus books that do not correspond to such elements but which cover specific 


ql be added to the ey in the 


ry is complete. 
ducts and will help us 
O need to mew about 


a 
" 
s An Online Index of all manu 
or added 
Every manual will include a roadmap that ¢ 


topics. 


At the present time we do: not have detailed schedules. Initially, we plan'to produce: 


a Descriptions for many classes and methods 

s A working draft of the Pink Foundation manual started in the form of an architectural 
overview document which is currently being written 
A start on the Online Glossary 

u Detailed document design for the Introduction to Pink 

a Detailed document design for the Operating System Kernel focus book (which will 
serve as a prototype document design for other focus books as well) 


We will publish firmer plans when we have evaluated our initial efforts. 
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Risks and concerns 


We have identified the following issues that put our plans and schedules at risk. We will be 
monitoring these issues during the following months. 


Staffing 


We have not yet determined exactly how many writers we will have, who they will be, or when 
they will join us. Who they are is important since the learning curve is going to be very steep. We 
are looking for experienced people, but since this is new technology there will still be lots to 
learn. We are pla rs to train new ones. While this pl il: help 
bring the new peo 


collaboratin 
We plan to‘usethe: 
Reference. This will allow’ 
Pink home. 


Weare currently writing using unst 
411 format. 


How to 
Pink progress 


And, of course, we are gated by the progress of Pink itself for the completion of the Pink 
Foundation, the Online Class and Method Reference, the nutshells, and the Human Interface Guidelines. 
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Attachment A: Summary of Products 


Product Content Audience 

Introduction Introduction to OOP and Pink Programming managers 

to Pink and programmers . 
learning 

Pink Foundation Overview of architecture; Programmers learning 
information for people who 


How to Write a 
Pink Application ictive 
Using HOOPS those 


Programmers:lé 


Online Class and 
Method Reference 


Focus Library 
Human Interface Guidelines fora 
Guidelines interfaces 


Online Glossary Definitions of terms 
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Attachment B: Currently Identified Focus Library 
Application Engine 


Application 
Document 
Views 

Events 
Commands 
Failure Handling 


Object Toolbox 


Text 
Graphics 
Operating Sys 
Utilities 
Network 
Sound 
Imaging 
Scripting 
Help 


Networking books 
TBD 


Other 


Runtime (memory management) 
File System 
Debugging 
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